OTel GenAI conventions: the names, and the ones that changed under you

Grep your codebase for the left column. Everything you find is either dead or reporting into a query nobody maintains any more.

That last row is the fastest dating test there is. If a page shows you five gen_ai.*.message events, it is describing the 2024 or 2025 spec, and you should assume everything else on the page is the same vintage. One event now carries the operation detail, and content rides on it or on the span.

Note the asymmetry between rows two and four. The token renames are safe mechanical substitutions. The content attributes are not: gen_ai.prompt was obsoleted rather than renamed, and the registry says so in those words. gen_ai.input.messages is a structured attribute with a mandatory JSON schema, not a string, and it is Opt-In rather than Recommended. Swapping the name without changing the shape produces telemetry that validates against nothing.

The reasonable objection to everything above is: if none of it is stable, why not invent my own names and be done with it? Three answers, in increasing order of how much they will matter to you.

• Renames are mechanical, inventions are not. prompt_tokens to input_tokens is a find-and-replace plus a dashboard edit. Migrating off a bespoke schema means re-deriving what you meant, usually from memory, usually during a migration you did not plan.
• The tooling reads these names. Grafana's AI dashboards, tail-sampling policies, and every LLM-aware backend key off gen_ai.*. Bespoke names mean you write the dashboards too.
• The requirement levels encode judgement you do not have to repeat. Someone already argued about whether temperature belongs on a span, whether tool arguments are sensitive, and which five attributes a sampler can afford to look at. Adopting the names adopts the arguments.

The honest position is: adopt the conventions, wrap the attribute keys in constants in one file, and expect to change that file once or twice a year. Do not scatter string literals through your codebase, because the whole point of a Development-status spec is that the strings will move.

Both Required attributes are enumerations with well-known values, which is what makes them safe as metric dimensions and as sampler predicates. Use the well-known value when one fits; the spec permits others, but every value you invent is a value no dashboard knows about.

Two things worth noticing. First, execute_tool, invoke_agent, invoke_workflow and plan appear both as span-name prefixes and as operation-name values, which is not redundant: the name is for humans reading a waterfall, the attribute is for machines grouping one. Set both.

Second, gen_ai.provider.name distinguishes the provider from the hosting platform, which is why aws.bedrock, gcp.vertex_ai and azure.ai.openai are values in their own right. If you call Claude through Bedrock, the platform is what your telemetry can actually observe, and b9 will show you why that distinction matters when one platform degrades and another does not.

Two pieces of token guidance that are easy to miss and expensive to miss. Report the billed count, not your own tokeniser's estimate, which is the only number that reconciles with an invoice. And fetch_response operations SHOULD NOT report token usage at all, because the tokens were billed on the original request and reporting them again double-counts.

This is the single most consequential sentence in the attribute registry for anyone who has to explain a bill:

So the arithmetic for cost is a weighted split of one number, not a sum of three. If you add all three you over-report input tokens on every cached request, and the over-report scales with how well your caching works - your cost dashboard gets worse precisely as your caching gets better. b4 does the full cost model with real multipliers; today just get the inclusion direction right in your head.

Worth naming the second, sharper trap now so it does not surprise you in b4: what a provider reports as input tokens and what the OTel attribute means are not automatically the same thing, and provider-side cache breakpoints can make the raw input_tokens field describe only part of the prompt. Log the breakdown, not just the total, and reconcile against a real invoice once before you trust any dashboard built on it.

Six attributes and two switches. The important design point is that gen_ai.tool.name is Required while the arguments are Opt-In, which means the default tool span tells you which tool ran and nothing about what it was asked. That is enough to catch wrong-tool-selection and not enough to catch a malformed argument. b6 makes that trade explicit; b10 makes it a policy.

Read the metric attribute lists and notice the absences: no conversation id, no response id, no user id, no tool call id. That is not an oversight, it is the cardinality guardrail written into the spec. Metric cost scales with the number of distinct time series, which is the Cartesian product of label values, so one unbounded label turns a cheap counter into an unbounded bill.

gen_ai.request.model is bounded at tens of values and is safe. gen_ai.conversation.id is unbounded and is not. The rule that follows: unbounded identifiers are fine on spans and never acceptable as metric dimensions. b7 works through the arithmetic and the collector configuration that enforces it.

There is one more signal worth knowing exists: the event gen_ai.evaluation.result, with gen_ai.evaluation.name, .score.value, .score.label and .explanation. Evaluation is becoming part of the telemetry spec rather than a separate discipline, which is a genuinely interesting development and the spine of b9.

The honest answer is that you often do not choose, because the dialect comes with the instrumentation package, and the package comes with whichever framework you are using. What you choose is where you normalise.

Notice that OpenInference has things the GenAI conventions simply lack: user.id, first-class cost, graph topology, and two span kinds - EVALUATOR and PROMPT - that describe parts of an LLM system the GenAI spec does not model as spans at all. Notice also that it is versioned, which for an operational dependency is worth real money.

Against that, gen_ai.* is what the generic tooling reads, what the tail-sampling examples are written against, and what a general-purpose APM will grow support for. And interop happens at the backend rather than at the producer: everyone emits OTLP and the platform normalises the names. Langfuse, for instance, documents reading OpenInference keys, gen_ai.* keys and MLflow keys.

So the practical rule: pick the dialect your instrumentation gives you, be consistent within one service, and put the normalisation in one place you control. What you must not do is emit both dialects from the same service and let each dashboard pick a favourite. a6 turns this into a buy-or-build decision.