> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# OpenInference Semantic Conventions
> How OpenInference and OpenTelemetry GenAI conventions compare, and how Arize AX normalizes gen_ai.* spans to OpenInference at ingestion.
> *"Standardized naming schemes and attribute definitions for telemetry data across services, languages, and platforms."*
A **semantic convention** is an agreement about what to call things. Without conventions, every team invents their own attribute names — one calls it `prompt`, another `input.text`, another `messages[0].content` — and tools that try to read all of those have to maintain mappings for every variant.
OpenInference defines the canonical attribute names for AI/LLM telemetry. Arize AX uses these conventions to render spans in the UI, and any OTel-compatible backend that understands OpenInference can do the same.
# Why Semantic Conventions Matter
Three concrete benefits, all of which compound as your stack grows:
| | What it gives you |
| :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
| **Consistency** | One name for each concept across services, languages, and platforms. Same key in Python, JS, and Go. |
| **Interoperability** | Tools and backends understand your data without custom mapping. Switching backends or layering on new tools doesn't require re-instrumenting. |
| **Best practices** | The conventions encode *what* to trace, not just *how*. They are an opinionated answer to "which attributes should I set on an LLM span?" |
Two examples of OpenInference attribute names:
```
llm.token_count.total
llm.input_messages
```
If you set `llm.input_messages` on a span, Arize AX knows it's the chat history. So does any other OpenInference-aware backend. So does anyone reading your trace export six months from now.
# OpenInference vs GenAI
The GenAI observability space currently has two semantic convention standards. They overlap in what they describe but differ in maturity and governance.
| | OpenInference | GenAI |
| :---------------------------- | :-------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Maintained by** | Arize | OpenTelemetry community |
| **Status** | Stable | Still in development; not on a stable release |
| **Stability guarantees** | Conventions are stable across releases. Breaking changes are versioned. | Conventions are subject to change at any time, with explicit guidance about version transitions and opt-in for newer experimental revisions. |
| **Attribute prefix** | Domain-specific prefixes: `llm.*`, `tool.*`, `agent.*`, `retriever.*`, etc. | Generally prefixed `gen_ai.*` |
| **Instrumentation libraries** | Extensive — auto-instrumentors for most popular AI frameworks. | Smaller surface area today; instrumentors are still landing. |
| **Arize AX support** | First-class. Arize AX reads these directly. | First-class. Arize AX normalizes `gen_ai.*` spans into OpenInference automatically at ingestion, so they render with the correct span kind, messages, token counts, and tool I/O. See [How Arize AX ingests GenAI spans](#how-arize-ax-ingests-genai-spans). |
Both conventions are first-class in Arize AX. If you are deciding what to instrument with, OpenInference still offers the richest fidelity, the strongest stability guarantees, and the widest auto-instrumentor coverage. But if your framework emits native OTel GenAI spans (for example, [Microsoft Agent Framework](/docs/ax/integrations/python-agent-frameworks/microsoft/microsoft-agent-framework) or CrewAI Studio), you no longer need a client-side processor to reshape them before export. Arize AX handles the normalization on ingestion, as the next section describes.
Over time the two conventions are expected to converge as the GenAI spec stabilizes. When that happens, the OpenInference auto-instrumentors will pick up the change so your application code does not have to.
# How Arize AX ingests GenAI spans
When a span reaches Arize AX carrying any attribute prefixed with `gen_ai.`, the ingestion pipeline normalizes it into the equivalent OpenInference attributes before the span is stored. The result is that spans instrumented purely with the OTel GenAI conventions render in the UI with the correct span kind, messages, token counts, tool inputs and outputs, and retrieved documents — the same treatment OpenInference spans receive.
No client-side reshape processor is required. Frameworks that emit native OTel GenAI spans, such as [Microsoft Agent Framework](/docs/ax/integrations/python-agent-frameworks/microsoft/microsoft-agent-framework) and CrewAI Studio, are ingested and rendered directly.
Three rules govern the normalization:
1. **Raw `gen_ai.*` attributes are preserved.** Normalization *adds* OpenInference attributes; it never removes the original GenAI ones, so your raw telemetry stays intact on the span.
2. **Explicit OpenInference attributes always win.** If a span already carries an OpenInference attribute (for example, your instrumentation set both `gen_ai.request.model` and `llm.model_name`), the existing OpenInference value is kept and the GenAI-derived value is discarded.
3. **Unrecognized operations stay unclassified.** The span kind is inferred from `gen_ai.operation.name`. An operation name that Arize AX does not recognize leaves the span kind unset rather than guessing.
Arize AX infers the span kind from `gen_ai.operation.name` and translates the payload — messages, tool calls and results, token usage, retrieved documents, and provider identity — onto the corresponding OpenInference attributes. For the complete span-kind classification and the full `gen_ai.*` → OpenInference attribute mapping, see [GenAI semantic convention mapping](/docs/ax/concepts/otel-openinference/span-kinds#genai-semantic-convention-mapping) on the Span Kinds reference page.
# The Authoritative Source
OpenInference is open-source. The canonical attribute lists, span kind enums, MIME type values, and LLM provider/system enums live in the OpenInference repository — language-specific implementations track these definitions exactly.
When in doubt about an exact attribute name, those files are the source of truth.
# What's Covered in OpenInference
The conventions cover four broad categories:
| Category | Examples | Where to read more |
| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Span kinds** | `LLM`, `TOOL`, `AGENT`, `CHAIN`, `RETRIEVER`, `EMBEDDING`, `RERANKER`, `GUARDRAIL`, `EVALUATOR`, `PROMPT`, `UNKNOWN` | [Span Kinds](/docs/ax/concepts/otel-openinference/span-kinds) |
| **Per-kind attributes** | `llm.input_messages`, `tool.parameters`, `agent.name`, `retrieval.documents` | [Span Kinds](/docs/ax/concepts/otel-openinference/span-kinds) |
| **Common attributes** | `input.value`, `output.value`, `input.mime_type`, `output.mime_type`, `metadata`, `session.id`, `user.id`, `tag.tags` | [Span Kinds](/docs/ax/concepts/otel-openinference/span-kinds#common-attributes-across-all-kinds) |
| **Enums** | LLM providers (`openai`, `anthropic`, `cohere`, ...), MIME types (`text/plain`, `application/json`), span kind values (ALL CAPS) | [Span Kinds](/docs/ax/concepts/otel-openinference/span-kinds) and the [canonical source](https://github.com/Arize-ai/openinference/blob/main/python/openinference-semantic-conventions/src/openinference/semconv/trace/__init__.py) |
The next page walks through the span-kind catalog in detail.
***
## Next step
Span kinds are the most important convention OpenInference adds — they determine how spans render in the Arize AX UI and which attributes are expected: