bug: otel-genai docs imply OTel lacks cache/reasoning token categories it already defines

[saintmalik]

Version or commit

16ab8e2 (origin/main); matrix pin open-telemetry/semantic-conventions-genai@a685613

Observed behavior

docs/otel-genai-compatibility.md says the pinned OTel convention defines a Histogram with input/output token types, then:

AgentTrust records additive, attribution-scoped facts and also distinguishes cache and reasoning categories.

That framing implies cache/reasoning are an AgentTrust-only distinction. At the matrix’s pinned upstream revision, OTel already defines span usage attributes including:

• gen_ai.usage.cache_read.input_tokens
• gen_ai.usage.cache_creation.input_tokens
• gen_ai.usage.reasoning.output_tokens

while gen_ai.token.type for gen_ai.client.token.usage remains only input / output.

compatibility/otel-genai.json metrics note for agentrust.usage.tokens similarly says AgentTrust records “additional token categories,” which overstates the gap the same way.

Expected behavior

The docs should not implying that OpenTelemetry lacks cache/reasoning token fields.

Accurate distinction:

• OpenTelemetry’s token histogram type is only input / output. Cache and reasoning tokens are tracked as separate span attributes in the pinned OTel version (they already exist upstream).
• What AgentTrust adds is attribution scope, labeling usage as belonging to a model_call, agent_step, task, agent_run, or workflow_run, not “we invented cache/reasoning and OTel did not.”

Minimal reproduction

1. Read https://github.com/agentrust-io/agentrust-telemetry/blob/16ab8e2/docs/otel-genai-compatibility.md#L31-L36
2. Read the metrics note at https://github.com/agentrust-io/agentrust-telemetry/blob/16ab8e2/compatibility/otel-genai.json#L36
3. At pin a685613a207a580163353b8e48a7ad88967e7b42, confirm OTel already names the cache/reasoning usage attributes, e.g. in gen-ai metrics/registry docs (gen_ai.usage.cache_read.input_tokens, gen_ai.usage.cache_creation.input_tokens, gen_ai.usage.reasoning.output_tokens) while gen_ai.token.type remains input/output only.

Environment and additional context

Docs/compatibility-claim accuracy only, no schema or SDK wire change.