“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. Phoenix 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:
If you set llm.input_messages on a span, Phoenix 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. |
| Phoenix support | First-class. Phoenix reads these directly. | Spans tagged with gen_ai.* attributes still arrive at Phoenix, but won’t get the same UI treatment as OpenInference-tagged spans. |
For new instrumentation today, use OpenInference. 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 doesn’t have to.
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, DECISION, PROMPT, UNKNOWN | Span Kinds |
| Per-kind attributes | llm.input_messages, tool.parameters, agent.name, retrieval.documents | Span Kinds |
| Common attributes | input.value, output.value, input.mime_type, output.mime_type, metadata, session.id, user.id, tag.tags | Span Kinds |
| Enums | LLM providers (openai, anthropic, cohere, …), MIME types (text/plain, application/json), span kind values (ALL CAPS) | Span Kinds and the canonical source |
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 Phoenix UI and which attributes are expected: