Services Case Studies Insights AI Readiness About Start a project →

OpenTelemetry's GenAI conventions: what to instrument before the spec stabilizes.

Observability Published August 29, 2026 9 min read

Why this matters right now

Every team running large language models or agents in production eventually hits the same wall: a request comes back slow, wrong, or expensive, and there is no trace connecting the model call to the tool invocations, retrieval step, or reasoning loop that produced it. Traditional application performance monitoring was not built for this. A span that says "call OpenAI" tells you nothing about which model actually answered, how many tokens it burned, whether a tool call inside an agent loop retried three times before failing, or which prompt version was live when the failure happened. For the last two years, every framework and every observability vendor solved this problem in its own way, which meant a trace exported from LangChain looked nothing like one exported from a raw OpenAI SDK call or a Claude agent loop, and comparing them across a multi-vendor stack meant writing your own translation layer by hand.

OpenTelemetry's GenAI semantic conventions exist to close that gap, and 2026 has been the year they moved from a side project inside the OpenTelemetry Semantic Conventions Special Interest Group to something vendors are actually shipping support for. Datadog added native support in OTel v1.37. Grafana started collecting LLM traces in Loki. That adoption curve is exactly why this matters now, teams are being asked to instrument against a standard that vendors already support, months before that standard has actually reached stability. Get the instrumentation choices right and you inherit a genuinely vendor-neutral observability layer for free. Get them wrong and you are looking at a second migration the day the schema locks.

What actually shipped, and what's still moving

The headline fact to understand before you touch a line of instrumentation code is this: as of mid-2026, every gen_ai.* attribute, span, metric, and event in the OpenTelemetry registry carries a stability badge of "Development," and none of them are marked "Stable." That is not a minor caveat. In OpenTelemetry's semantic convention process, "Development" means the schema can still change in a breaking way, field names can be renamed, and enumeration values can be redefined, without the multi-year deprecation guarantees that apply to stable conventions like HTTP or database spans.

The bigger structural change landed on June 12, 2026, with semantic-conventions release v1.42.0, which deprecated the GenAI conventions inside the main OpenTelemetry semantic-conventions repository and moved them into a dedicated repository, open-telemetry/semantic-conventions-genai. That move was an organizational decision, not a maturity milestone. Splitting GenAI work into its own repository gives the fastest-moving parts of the spec, agent spans, tool call attributes, token accounting, their own release cadence, separate from the slower, stability-bound core HTTP and database conventions most of OpenTelemetry has already settled on. As of this writing, that dedicated repository has not tagged a single release. There is no versioned schema URL to pin your instrumentation against yet, and no public commitment to a stabilization date.

What the spec actually covers today

  • Model invocation spans capture the request and response for a single call to a model, with attributes for the model name, the provider, input and output token counts, and finish reason.
  • Agent and tool spans nest under a parent invocation to represent each step in an agent's reasoning loop, so a single user request can expand into a full tree of model calls, tool invocations, and retrieval steps.
  • Embedding and retrieval spans cover vector database queries and embedding calls, letting a RAG pipeline's retrieval latency show up next to the generation latency it feeds.
  • Content capture is opt-in and kept separate from the trace attributes, reflecting a deliberate design decision to keep prompt and completion text out of default telemetry given how sensitive that data usually is.

What to instrument today, despite the instability

The instinct to wait for a stable release is understandable and, for most teams, wrong. Waiting means running blind on cost and latency for a system that is very likely already your fastest-growing infrastructure line item, and it means building whatever stopgap dashboards you improvise in the meantime, then throwing them away later anyway. The better approach is to instrument today against the current conventions while explicitly isolating yourself from the churn.

  • Wrap the OpenTelemetry GenAI attributes behind your own thin abstraction rather than scattering gen_ai.* attribute names through application code. When a field gets renamed in the next spec revision, you update one mapping layer instead of every call site.
  • Instrument token counts and cost per call from day one. This is the single highest-value signal in the entire spec, and it is stable in spirit even where field names are not, since every model provider already returns token usage in its response payload today.
  • Capture the full span tree for agent workloads, not just the top-level request. A latency problem in a five-step agent loop is invisible if your only span is "handle user request." Nest tool calls and sub-invocations so you can see exactly which step in the chain is slow or retrying.
  • Treat content capture as a separate, explicit decision. Log prompts and completions to a scoped, access-controlled sink if you need them for debugging, and keep that data out of your general tracing backend, where retention policies and access controls are usually looser than they should be for raw model input and output.
  • Pin your instrumentation library version and track the changelog for whichever SDK or auto-instrumentation package you use, rather than auto-upgrading and discovering a renamed attribute inside a live dashboard.

Trade-offs and the vendor landscape

Two camps have formed around this problem, and the choice between them is a real architectural decision, not a matter of taste. The first camp is OTel-native: instrument with the GenAI semantic conventions and ship spans to whatever backend already ingests your existing OpenTelemetry traces, Datadog, Grafana, Honeycomb, or a self-hosted collector. The appeal is consolidation. Your AI observability lives next to your service observability, correlated in the same trace, queried with the same tools your on-call team already knows.

The second camp is purpose-built LLM observability platforms such as Langfuse and Helicone, which predate the GenAI conventions and offer richer, LLM-specific features out of the box, prompt versioning, evaluation scoring, and dataset management alongside the tracing itself. Several of these platforms have added OpenTelemetry compatibility as an ingestion path rather than replacing their own schema internally, which means you can often get the best of both by exporting OTel-shaped spans into a specialized backend while keeping the option to point the same data at a general-purpose observability platform later.

The practical trade-off is depth versus consolidation. A dedicated LLM observability tool will almost always give you better prompt-level debugging and evaluation workflows today. A general-purpose OTel backend gives you a single pane of glass across your whole system and a smaller number of vendor relationships to manage, at the cost of a rougher edge on LLM-specific features while the conventions mature. Most teams we work with end up running both for a period, using the specialized tool for prompt engineering and evaluation work, and the general OTel pipeline for the operational questions, is the system up, is it slow, is it expensive, that an on-call engineer needs answered at 2am without learning a new tool.

A rollout plan that survives the next schema change

Given the instability, sequence the work so that a future breaking change costs you a config update, not a rewrite. Start by instrumenting the highest-value, lowest-churn signals first, token usage and cost per model call, since providers have already stabilized their own response payloads regardless of what OpenTelemetry ends up calling the resulting attribute. Layer in latency and error rate per model and per provider next, since these map cleanly onto dashboards and alerts your team already understands from non-AI services. Only after those two layers are solid should you invest in the deeper agent and tool span trees, since that is the part of the spec most likely to see structural changes as the GenAI SIG works through how deeply nested agent reasoning should be represented.

  • Build the mapping layer first. A single module that translates your internal event shape into gen_ai.* attributes means the migration on the day the spec stabilizes touches one file, not your whole codebase.
  • Alert on cost and error rate before you build fancy dashboards. A page that fires when spend or failure rate crosses a threshold is worth more in the first quarter than a beautifully instrumented trace nobody looks at until something breaks.
  • Review your instrumentation against the spec quarterly, not continuously. The GenAI conventions move fast enough that chasing every change is wasted effort, but slowly enough that a quarterly review catches breaking changes before they surprise you in production.

Practical takeaways

The absence of a stable release is not a reason to sit this one out. It is a reason to instrument deliberately, behind an abstraction you control, focused on the signals, cost, latency, and error rate, that matter regardless of how the underlying attribute names shake out. Teams that wait for stability will spend 2027 retrofitting observability onto AI systems that have been running blind for a year. Teams that instrument now, with a thin mapping layer between their code and the OpenTelemetry attributes, will spend that same year making a config change instead of a rewrite. If you are building out this observability layer alongside a broader production AI rollout, that scoping work, including where tracing fits your existing stack and compliance requirements, is exactly the kind of engagement we run as part of our AI infrastructure consultancy. Start with the cost and latency signals you can capture today, and let the agent-level detail follow once the spec settles.

Keep reading

Building out observability for a production AI system?

Start a conversation →
KT Solutions Assistant

Before we start, please share a few details so we can follow up with you.

Please enter your name and a valid email address.

End this conversation? Your chat will be emailed to us.