Skip to main content

Documentation Index

Fetch the complete documentation index at: https://arize-ax.mintlify.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

A span kind is the category of operation a span represents. OpenTelemetry has its own span kinds for network calls (SERVER, CLIENT, PRODUCER, …). OpenInference adds an AI-specific set: LLM, Tool, Agent, Chain, Retriever, and more. Span kind is what drives the span-kind icons in the Arize AX UI. It’s also how Arize AX knows which attributes to expect — an LLM span gets a different visual treatment from a tool span.

​
Setting the Span Kind

Span kind is set via the openinference.span.kind attribute. The value is ALL CAPS — "TOOL", not "Tool". Casing matters: the canonical OpenInference Python enum is OpenInferenceSpanKindValues.TOOL = "TOOL". 
from openinference.semconv.trace import (
    SpanAttributes,
    OpenInferenceSpanKindValues,
)

span.set_attribute(
    SpanAttributes.OPENINFERENCE_SPAN_KIND,
    OpenInferenceSpanKindValues.TOOL.value,
)
Arize AX UI behavior: span-kind icons in the Arize AX trace tree come directly from the openinference.span.kind attribute. A span without that attribute renders with a blank icon. Auto-instrumentors set this for you — set it explicitly on every manual span.

​
The Eleven Span Kinds

OpenInference defines eleven span-kind values. The first four (LLM, Chain, Agent, Tool) are the ones you’ll encounter most often:
IconSpan kindDescription
LLM span-kind iconLLMA call to a large language model.
Chain span-kind iconCHAINA starting point or a link between different LLM application steps.
Agent span-kind iconAGENTA span that encompasses calls to LLMs and tools — typically the top-level wrapper for an agent loop.
Tool span-kind iconTOOLA span that represents a call to an external tool, API, or function on behalf of an LLM.
Retriever span-kind iconRETRIEVERA data retrieval query for context from a datastore (e.g., a vector DB query).
Embedding span-kind iconEMBEDDINGAn encoding of unstructured data into a vector.
Reranker span-kind iconRERANKERA relevance-based re-ordering of documents.
Guardrail span-kind iconGUARDRAILA validation of LLM input or output for safety, policy, or compliance.
Evaluator span-kind icon (falls back to Unknown)EVALUATORAn evaluation process — the type, configuration, and results.
Prompt span-kind icon (falls back to Unknown)PROMPTA span representing prompt construction or templating.
Unknown span-kind iconUNKNOWNDefault when no kind is set explicitly.

​
Common Attributes Across All Kinds

These attributes apply to every span kind. Auto-instrumentors set them automatically; set them yourself on every manual span:
AttributePurpose
openinference.span.kindThe span kind (ALL CAPS — e.g., "LLM").
input.valueThe span’s input. Free-form string or serialized JSON.
input.mime_type"text/plain" (default) or "application/json". The TS semconv also defines "audio/wav".
output.valueThe span’s output.
output.mime_type"text/plain" (default) or "application/json". The TS semconv also defines "audio/wav".
metadataArbitrary JSON-stringified metadata.
session.idGroups traces into a session. See Sessions.
user.idThe user the request belongs to.
tag.tagsA list of tags for filtering and search.
Arize AX UI behavior: Arize AX reads the trace-level input and output from the root span’s input.value and output.value. If your root span doesn’t set them, the trace list view shows those columns as blank even if child spans have data.

​
Per-Kind Attributes

The four most-used kinds have a richer attribute set. The full list lives in the OpenInference semantic conventions — the tables below are a summary.

​
LLM

A call to a large language model.
AttributeDescription
llm.model_nameThe model identifier (e.g., gpt-4o, claude-3-5-sonnet-20241022).
llm.providerThe provider (e.g. openai, anthropic, mistralai).
llm.systemThe underlying LLM system, when distinct from provider.
llm.input_messagesThe chat history sent to the model.
llm.output_messagesThe model’s response messages.
llm.invocation_parametersTemperature, top-p, max tokens, etc. (JSON-stringified).
llm.toolsTool definitions exposed to the model.
llm.function_callFunction call returned by the model (legacy).
llm.promptsThe raw prompts sent (for completion-style APIs).
llm.choicesThe choices returned by the model.
llm.prompt_template.templateThe prompt template before variable substitution.
llm.prompt_template.variablesThe variables substituted into the template.
llm.prompt_template.versionA version identifier for the template.
llm.token_count.totalTotal tokens.
llm.token_count.promptPrompt tokens.
llm.token_count.completionCompletion tokens.
llm.token_count.prompt_details.*Breakdown of prompt tokens (cached, audio, etc.).
llm.token_count.completion_details.*Breakdown of completion tokens.
llm.cost.totalTotal cost.
llm.cost.prompt, llm.cost.completionPer-direction cost.
llm.cost.*_details.*Breakdown of cost by token type.
llm.finish_reasonWhy the model stopped generating (stop, length, tool_calls, …).

​
TOOL

A call to an external tool, API, or function on behalf of an LLM.
AttributeDescription
tool.idA unique identifier for the tool invocation (often correlated with the LLM’s tool-call ID).
tool.nameThe tool’s name.
tool.descriptionThe tool’s description (often matches what was shown to the model).
tool.parametersThe JSON-serialized parameters passed to the tool.
tool.json_schemaThe tool’s full JSON schema as exposed to the model.
Tool calls are one of the clearest cases where you must instrument manually when making an LLM calls directly, instead of via a framework. When you call OpenAI directly, the auto-instrumentor traces the model’s request for a tool call — but the actual execution of the tool function happens in your Python code, where the instrumentor can’t see it. Wrap the function in a tool span yourself.

​
AGENT

A span that encompasses calls to LLMs and tools — typically the top-level wrapper for an agent loop.
AttributeDescription
agent.nameThe agent’s name.
graph.node.idNode ID for graph-based agent frameworks (e.g., LangGraph).
graph.node.nameNode display name.
graph.node.parent_idParent node ID, for graph traversal visualization.

​
CHAIN

A starting point or a link between different application steps. Use a chain span to group pre/post-processing logic that doesn’t fit any of the more specific kinds. Chain spans use only the common attributes — input.value, output.value, metadata, session.id, etc.

​
Other Kinds

The remaining seven span kinds — RETRIEVER, EMBEDDING, RERANKER, GUARDRAIL, EVALUATOR, PROMPT, UNKNOWN — each have their own attribute schemas. Consult the canonical source for the full per-kind attribute list.

​
Multimodal Message Content

Inputs and outputs in modern AI applications aren’t always plain text. OpenInference defines a message_content attribute family for multimodal content:
AttributeDescription
message_content.typeOne of text, image, audio, reasoning, tool_use.
message_content.textThe text payload (when type is text or reasoning).
message_content.imageThe image payload — URL or inline base64 (when type=image).
message_content.idProvider-assigned identifier for the message content item (e.g., OpenAI Responses reasoning IDs).
message_content.signatureOpaque vendor-issued signature (e.g., Gemini thoughtSignature).
message_content.dataOpaque vendor-issued data (e.g., Anthropic redacted_thinking.data).
message_content.encrypted_contentEncrypted payload for sensitive content (e.g., OpenAI encrypted_content).
For audio specifically, OpenInference exposes a separate set of attributes — audio.url, audio.mime_type, audio.transcript — see the canonical source.

​
How a Trace Tree Uses Span Kinds

A typical agent trace nests span kinds inside each other: 
AGENT span                         (agent.name = "research-assistant")
├── LLM span                       "decide next step"
├── TOOL span                      "search knowledge base"
│   └── RETRIEVER span             "vector search"
│       └── EMBEDDING span         "embed query"
└── LLM span                       "answer with retrieved docs"
Each level has its own kind, its own attributes, and its own rendering in the Arize AX UI. The combination is what makes agent behavior legible. Trace in Arize AX from the OpenAI Agents SDK example, showing agent, chain, tool, and LLM spans nested together

​
Next step

You know what attributes go on a span. Next, the three ways to actually emit spans — auto, manual, and hybrid:

Next: Instrumentation Approaches