OpenInference Semantic Conventions

OpenInference Semantic Conventions#

OpenInference Semantic Conventions define the attribute keys and values that describe AI/LLM operations on distributed traces. They are designed to be complementary to OpenTelemetry — not a replacement — providing AI-specific span attributes that work alongside standard OTel infrastructure and any OTLP-compatible backend.

The spec is transport- and format-agnostic and is natively consumed by Arize Phoenix. Attributes follow a dotted-path namespace (e.g. llm.token_count.prompt, retrieval.documents), stored as flat keys in OTLP and unflattened into nested JSON inside Phoenix .

Canonical sources:

Spec: spec/semantic_conventions.md — full attribute table with types and examples
Spec: spec/traces.md — span kinds, status, and transport notes
Python package: openinference-semantic-conventions on PyPI
JS/TS package: @arizeai/openinference-semantic-conventions

Attribute Namespaces#

All attributes are defined in the spec table and mirrored in both language packages. The top-level prefixes are :

Prefix	Domain
`input.` / `output.`	Generic span input/output value and MIME type
`llm.*`	LLM calls — messages, model name, provider, system, token counts, cost, invocation params, tools, prompt templates
`retrieval.*`	Retrieved document lists
`reranker.*`	Reranker query, model, top-k, input/output documents
`embedding.*`	Embedding model name, text, and vector
`message.*`	Per-message role, content, tool calls inside `llm.input_messages` / `llm.output_messages`
`message_content.*`	Multi-part message content (text, image)
`tool.` / `tool_call.`	Tool definition and invocation
`document.*`	Individual document attributes (id, content, score, metadata)
`session.` / `user.`	Session and user correlation IDs
`openinference.*`	OpenInference-specific metadata (e.g. `openinference.span.kind`)
`agent.*`	Agent name
`graph.*`	Execution graph node id, name, and parent id
`metadata`	Free-form user-defined span metadata (JSON string)
`tag.*`	Categorical span tags
`audio.*`	Audio URL, MIME type, and transcript
`prompt.*`	Prompt vendor, id, and URL

Python#

The Python package exposes a SpanAttributes class for top-level attributes and separate classes for nested contexts: MessageAttributes, DocumentAttributes, EmbeddingAttributes, RerankerAttributes, ToolCallAttributes, ToolAttributes, MessageContentAttributes, ImageAttributes, and AudioAttributes.

JavaScript / TypeScript#

The JS/TS package exports a flat SemanticConventions const object plus individual postfix groups (e.g. LLMAttributePostfixes, MessageAttributePostfixes).

OTLP Serialization#

Attributes whose values are lists of objects (e.g. llm.input_messages, retrieval.documents) must be flattened when written as OTel span attributes . Phoenix's ingestion pipeline performs the reverse unflatten on receipt .

Span Kinds#

OpenInference defines its own span kind taxonomy, stored in the openinference.span.kind span attribute — distinct from OTel's native span.kind field (see § Relationship to OpenTelemetry) .

Kind	Description
`LLM`	A call to a language model
`CHAIN`	Orchestration / glue code linking steps; also used as the root span of a request
`RETRIEVER`	A data retrieval step, e.g. vector store or database lookup
`RERANKER`	Reranking a set of input documents, e.g. a cross-encoder
`EMBEDDING`	Embedding generation
`AGENT`	An agentic loop
`TOOL`	A tool / function call
`GUARDRAIL`	Content safety / filtering
`EVALUATOR`	Evaluation span run
`UNKNOWN`	Fallback

Python enum: OpenInferenceSpanKindValues. JS/TS enum: OpenInferenceSpanKind.

Relationship to OpenTelemetry gen_ai Conventions#

OpenInference is complementary to OpenTelemetry, not a fork or replacement . It does not map 1-to-1 onto OTel's gen_ai.* semantic conventions — it predates them and uses different naming schemes (llm.* vs. gen_ai.*). Key differences and integration points:

Namespace: OpenInference uses llm.*, retrieval.*, embedding.*, etc. OTel gen_ai uses gen_ai.*. There is no official translation layer documented in the OpenInference repository.
Span kind conflict: OTel already has a first-class span.kind concept (SERVER, CLIENT, etc.). OpenInference's richer AI-specific kind (LLM, CHAIN, RETRIEVER…) is therefore stored as a span attribute — openinference.span.kind — to avoid collision .
Transport: OpenInference attributes are emitted as standard OTel span attributes over OTLP. List-of-object values must be flattened to scalar types before export ; Phoenix unflattens them back on ingestion .
Backend compatibility: Because attributes ride standard OTLP spans, any OTel-compatible backend can receive them. Phoenix provides first-class indexing and UI support for the full OpenInference attribute set.

When building new instrumentation, use OpenInference attributes for AI-specific metadata and rely on OTel's standard attributes (HTTP, RPC, etc.) for infrastructure-level metadata.