Attributes And Span Kinds

Both Catalyst tracing SDKs export the OpenInference attribute keys and span kinds they emit. Use them when you author manual spans, when you need to filter on a specific attribute from the CLI, or when you want to understand what each span in the trace tree should carry. Attr is not a whitelist. A span is an ordinary OpenTelemetry span, so you can set any key you like with setAttribute (see custom attributes). The keys below are the ones the dashboard understands: set Attr.MODEL_NAME (llm.model_name) and it shows the model and computes cost; set Attr.SESSION_ID (session.id) and it groups the conversation. Attr just spares you from typing, and mistyping, the wire keys by hand. The wire-format values are byte-identical to the upstream OpenInference semantic conventions, so OpenInference-aware viewers render Catalyst spans without configuration.

import { Attr, SpanKindValues } from "@inference/tracing";

from inference_catalyst_tracing import Attr, SpanKindValues

Span Kinds

SpanKindValues is the canonical set of values for the openinference.span.kind attribute. Pick the kind that best describes the work the span wraps.

Kind	Constant	Use For	Required Attributes	Common Optional Attributes
`AGENT`	`SpanKindValues.AGENT`	The outer span around an agent run	`SPAN_KIND`, `AGENT_ID`	`AGENT_NAME`, `AGENT_ROLE`, `SESSION_ID`, `USER_ID`, `SYSTEM`, `INPUT_VALUE`, `OUTPUT_VALUE`, `MODEL_NAME`, token counts
`LLM`	`SpanKindValues.LLM`	One LLM call (chat, completion, embedding-as-LLM)	`SPAN_KIND`, `MODEL_NAME`	`SYSTEM`, `LLM_SYSTEM`, `LLM_PROVIDER`, `INVOCATION_PARAMETERS`, `STREAMING`, `FINISH_REASON`, message attributes, token counts
`TOOL`	`SpanKindValues.TOOL`	A tool invocation by an agent	`SPAN_KIND`, `TOOL_NAME`	`TOOL_CALL_ID`, `INPUT_VALUE`, `OUTPUT_VALUE`, `INPUT_MIME_TYPE`, `OUTPUT_MIME_TYPE`
`CHAIN`	`SpanKindValues.CHAIN`	A chain step that is not itself an LLM call (router, postprocessor, planner)	`SPAN_KIND`	`INPUT_VALUE`, `OUTPUT_VALUE`, free-form attributes
`RETRIEVER`	`SpanKindValues.RETRIEVER`	A vector-search or document-lookup call	`SPAN_KIND`	`INPUT_VALUE` (the query), `OUTPUT_VALUE` (the results)
`EMBEDDING`	`SpanKindValues.EMBEDDING`	An embedding-model call your code makes directly	`SPAN_KIND`, `MODEL_NAME`	`INPUT_VALUE`, token counts

The patched provider SDKs emit LLM-kind spans automatically with all required and most optional attributes filled in. You only need to author LLM spans manually if you are wrapping an SDK Catalyst does not patch.

Attribute Constants

All attributes are exported on the Attr object. The constant name is the left-hand column; the wire-format key in the right-hand column is what actually goes on the span.

Span Identity

Constant	Wire key	On
`Attr.SPAN_KIND`	`openinference.span.kind`	Every span
`Attr.SESSION_ID`	`session.id`	Any span, used for conversation grouping
`Attr.USER_ID`	`user.id`	Any span, used for filtering traces by user

Agent Identity

Set on AGENT spans, copied onto child LLM/TOOL spans by the per-SDK patchers and by agentSpan() / agent_span() when the child is created in the active context.

Constant	Wire key	Purpose
`Attr.AGENT_ID`	`agent.id`	Stable identifier for grouping in the Agents dashboard
`Attr.AGENT_NAME`	`agent.name`	Human-readable label
`Attr.AGENT_ROLE`	`agent.role`	Role in a multi-agent workflow (e.g. `triage`, `refunds`)

Inputs And Outputs

Constant	Wire key	Notes
`Attr.INPUT_VALUE`	`input.value`	Stringified input. JSON-encode structured values.
`Attr.OUTPUT_VALUE`	`output.value`	Stringified output.
`Attr.INPUT_MIME_TYPE`	`input.mime_type`	Typically `"application/json"` or `"text/plain"`.
`Attr.OUTPUT_MIME_TYPE`	`output.mime_type`	Same.

Model And Provider

Set on LLM and EMBEDDING spans. Also useful on AGENT spans to declare the provider the agent runs on.

Constant	Wire key	Notes
`Attr.MODEL_NAME`	`llm.model_name`	Prefer the model the API echoed back.
`Attr.SYSTEM`	`gen_ai.system`	Provider identifier on AGENT spans (`"openai"`, `"anthropic"`).
`Attr.LLM_SYSTEM`	`llm.system`	Provider identifier on LLM spans.
`Attr.LLM_PROVIDER`	`llm.provider`	Alternate provider identifier on LLM spans.
`Attr.INVOCATION_PARAMETERS`	`llm.invocation_parameters`	JSON of the request parameters (temperature, max_tokens, etc.).
`Attr.STREAMING`	`llm.streaming`	Boolean. Did the call stream.
`Attr.FINISH_REASON`	`llm.finish_reason`	Provider finish reason.

Token Usage

Constant	Wire key
`Attr.TOKEN_COUNT_PROMPT`	`llm.token_count.prompt`
`Attr.TOKEN_COUNT_COMPLETION`	`llm.token_count.completion`
`Attr.TOKEN_COUNT_TOTAL`	`llm.token_count.total`
`Attr.TOKEN_COUNT_PROMPT_CACHE_WRITE`	`llm.token_count.prompt_details.cache_write`
`Attr.TOKEN_COUNT_PROMPT_CACHE_READ`	`llm.token_count.prompt_details.cache_read`
`Attr.TOKEN_COUNT_COMPLETION_REASONING`	`llm.token_count.completion_details.reasoning`

The per-SDK patchers fill these in automatically when the provider returns usage. For manual spans, use the helpers on the span handle:

TypeScript: span.recordTokens({ prompt, completion, total }) to pass the counts directly.
Python: span.record_tokens(prompt=..., completion=..., total=...) for manual counts, or span.record_usage(response.usage) to let the SDK normalize an OpenAI- or Anthropic-shaped usage object (including cache fields).

Tools

Set on TOOL spans. Also set on LLM spans by the provider patchers when the LLM emits a tool_use block, so the dashboard can show the tool the model asked for.

Constant	Wire key
`Attr.TOOL_NAME`	`tool.name`
`Attr.TOOL_CALL_ID`	`tool_call.id`
`Attr.AGENT_TOOL_CALL_COUNT`	`agent.tool_call_count`
`Attr.AGENT_LLM_CALL_COUNT`	`agent.llm_call_count`

Messages

LLM spans emit per-message attributes for each input and output message. The keys are indexed and machine-generated. Use the OpenInferenceAttribute helper to compose them rather than hand-rolling the strings.

TypeScript

import { OpenInferenceAttribute } from "@inference/tracing";

const prefix = OpenInferenceAttribute.inputMessagePrefix(0);
span.setAttribute(OpenInferenceAttribute.role(prefix), "user");
span.setAttribute(OpenInferenceAttribute.content(prefix), "Hello");

The wire keys take the form llm.input_messages.0.message.role, llm.input_messages.0.message.content, llm.output_messages.0.message.role, and so on. For tool-call messages, the helper also generates ...tool_calls.0.tool_call.function.name, ...tool_calls.0.tool_call.function.arguments, and ...tool_calls.0.tool_call.id. You rarely need to author these by hand; the per-SDK patchers emit them. This block is here so the keys are searchable when you are debugging captured output.

Using Attributes From The CLI

The same attribute keys are filterable from inf trace and inf span:

# Find all TOOL spans for one tool name
inf span list --kind TOOL --metadata "tool.name=lookup_order"

# Find traces from one conversation
inf trace list --metadata "session.id=conversation-ticket-123"

# Find all traces for one user
inf trace list --metadata "user.id=user_8675309"

# Find expensive LLM spans, sorted by cost
inf span list --kind LLM --filter "cost_total>0.05" --sort cost_total --order desc

See inf span and inf trace for the full filter syntax.

Next Steps

Handle API reference

The typed methods on agentSpan / manual_span handles that write these attributes for you.

Manual spans

Author TOOL, CHAIN, and RETRIEVER spans inside your agent loop.

Agent identity

Pick stable agent.id and session.id values for the Agents dashboard.

CLI span reference

Filter, search, and inspect spans by attribute from the terminal.

Integrations

Traces

Gateway

Span Kinds

Attribute Constants

Span Identity

Agent Identity

Inputs And Outputs

Model And Provider

Token Usage

Tools

Messages

Using Attributes From The CLI

Next Steps

Handle API reference

Manual spans

Agent identity

CLI span reference

​Span Kinds

​Attribute Constants

​Span Identity

​Agent Identity

​Inputs And Outputs

​Model And Provider

​Token Usage

​Tools

​Messages

​Using Attributes From The CLI

​Next Steps

Handle API reference

Manual spans

Agent identity

CLI span reference

Span Kinds

Attribute Constants

Span Identity

Agent Identity

Inputs And Outputs

Model And Provider

Token Usage

Tools

Messages

Using Attributes From The CLI

Next Steps