Semantic Telemetry: Capturing Reasoning, Tool Calls, and Decision Provenance with OpenTelemetry GenAI

A conventional trace answers a spatial question: where in the call graph did the time and the work go. That is the right question for a service whose behavior is a function of its code path. It is the wrong question for an agent, whose behavior is a function of what it understood, what it retrieved, and what it decided to do with a tool. To observe an agent you have to record meaning - the plan it formed, the evidence it consumed, the actions it took and under whose authority - and bind those together so a later reader can reconstruct not just the timing but the reasoning. This article specifies that semantic layer: a concrete span schema on top of the OpenTelemetry generative-AI conventions, a provenance model that links claims to their evidence, and the privacy discipline that keeps the telemetry from becoming its own liability.

Why Semantics, Not Just Spans

A span that records a start time, a duration, and a status is a syntactic record: it captures that work happened and how long it took. Semantic telemetry is the deliberate capture of what the work meant - the intent behind a call, the plan an agent formed, the specific documents that grounded an answer, the arguments passed to a tool, and the content of the result. The distinction matters because the failures that hurt in AI systems are semantic: a wrong grounding, an over-broad tool call, a plan that quietly changed goals.

The design goal is a trace you can interrogate rather than merely watch. A syntactic trace lets you ask which span was slow. A semantic trace lets you ask why the agent chose that tool, what evidence supported the claim it made, and whether the action it took was authorized. Those are the questions an incident review, a compliance audit, and a regression hunt all actually need answered.

Reaching that requires two things this article develops in turn: a shared schema for the spans and their attributes, so the capture is portable rather than bespoke; and a provenance layer that links the pieces, so the trace is a connected account of a decision rather than a pile of unrelated events.

The OpenTelemetry Conventions for Generative AI

The portability problem has a maturing answer. The OpenTelemetry project publishes semantic conventions for generative AI: a standardized vocabulary of span names and attributes for model calls, tool calls, and agent operations - the model and system identifiers, token-usage counts, tool names and arguments, and the message events that make up an interaction. Adopting a shared convention means a trace emitted by one framework can be read, queried, and correlated by any backend that understands the convention, instead of every team inventing its own attribute names.

Two properties make the conventions the right foundation. They are vendor-neutral, so the semantic layer is not welded to a single observability product. And they are extensible: the standard names cover the common cases, and you attach your own attributes - an eval score, a provenance link, an authority context - for the parts specific to your system. The convention is a floor to build on, not a cage.

What the conventions deliberately do not do is decide your policy: how much of a prompt to store, what to hash, which fields are sensitive. Those are the design decisions the rest of this article is about, and they are where a naive adoption of the standard goes wrong.

A Span Schema for a Decision

Concretely, model one agent decision as a root span with typed children. The root is the decision itself; its children are the model call (with model, version, sampling parameters, and token usage), each tool call (with the tool name, an argument hash, and a result summary), each retrieval (with the document identifiers and similarity scores that grounded the answer), and the eval that scored the output. The attributes are what turn a span from a timer into a record of meaning.

The schema also decides representation, which is where privacy and cost enter. Not every field should be stored verbatim: identifiers and hashes preserve the ability to correlate and to detect change while shedding most of the sensitive payload. The table below is a compact schema you can adopt directly, pairing each attribute with what it captures and how to store it.

The rule of thumb is to capture structure faithfully and content selectively: always record which documents grounded an answer and which tool ran with what shape of argument; record the raw text only where it is both necessary and governed.

Decision Provenance: Binding Claims to Evidence

Recording that retrieval happened is not the same as knowing why the model said what it said. Decision provenance is the missing link: for each claim in an output, the set of evidence spans, tool results, and sources that support it. Formally, treat provenance as a relation from a claim to the evidence that grounds it - a small structure attached to the decision span that answers, per assertion, what backed it up.

This is what upgrades a trace from a timeline into an audit. With provenance, an operator investigating a wrong answer does not guess which of five retrieved documents misled the model; they follow the provenance link from the offending claim to the exact evidence, and from there to its source. Without it, the retrieved documents are present in the trace but unattached, and the crucial question - which one grounded this sentence - is unanswerable.

Provenance also draws the trust boundary explicitly. Retrieved content is untrusted input; binding a claim to a retrieved span records not only support but exposure - a claim grounded solely in attacker-controllable content is exactly the pattern indirect-injection defenses need to surface.

Capturing Reasoning Without Capturing Everything

Semantic telemetry has a dangerous failure mode of its own: to capture reasoning it collects prompts, plans, and retrieved documents - precisely the material most likely to contain personal data, secrets, or regulated content. Instrumenting an agent naively can turn your trace store into the single richest target in the system, and the OWASP Top 10 for LLM Applications lists sensitive-information disclosure as a first-class risk for exactly this reason.

The discipline is to capture the structure needed for observability while minimizing the raw content retained. Hash arguments and inputs so you can detect change and correlate without storing the payload; keep document identifiers rather than document text; redact or tokenize known-sensitive fields at the point of emission, before telemetry leaves the process; and sample raw captures rather than retaining every one. The NIST AI Risk Management Framework's treatment of privacy as a core trustworthiness characteristic is the governing principle: the telemetry must not itself become the breach.

This is a genuine trade-off, not a solved problem. Hashing an argument loses the ability to read it later; sampling raw content means some incident will lack the exact prompt. The right posture is to make the trade deliberately per field, and to hold the retained sensitive content to the same access controls as the production data it came from.

Provenance of Action: Recording Tool Authority

For an agent, the highest-consequence spans are tool calls, and the attribute that makes them auditable is authority: under which credential and scope was the action taken. A tool call span that records only the tool name and arguments cannot answer whether the agent was permitted to do what it did. One that also records the authority context - the identity, the granted scope, and the least-privilege decision - turns confused-deputy and excessive-agency failures from invisible into reviewable.

The pattern is to make authority a first-class step in the recorded flow: a request to use a tool, an explicit authority check against the caller's scope, the tool call itself constrained to least privilege, and a result that records both the outcome and the authority under which it happened. The OWASP Top 10 for LLM Applications calls out excessive agency directly; recording authority is how observability gives that risk a signal.

This closes the loop with provenance: evidence provenance answers why the model believed something, and action provenance answers under what authority it acted. Together they make a decision fully accountable.

From Semantic Trace to Answerable Questions

The payoff of the schema and the provenance layer is a set of questions that become answerable, which timing alone can never touch. Why did the agent act - recoverable from the plan span and the decision provenance. What grounded a specific claim - recoverable from the evidence provenance. Which tool overreached - recoverable from the authority records. And could we replay this decision - recoverable because the semantic trace preserves the inputs, evidence, and choices, not just the durations.

This is the traceability that the NIST AI Risk Management Framework's MEASURE and MANAGE functions call for and that its Generative AI Profile frames as necessary for governing generative systems. A semantic trace is the concrete artifact that makes those governance expectations checkable rather than aspirational: an auditor can follow a real link from an outcome to its cause.

The questions, not the spans, are the point. Instrument backward from what an incident review will need to ask, and the schema follows; instrument from what is easy to emit, and you rebuild a latency dashboard with extra fields.

Threats to Validity, and an Honest Limit

The semantic layer has costs and one deep caveat. The costs are familiar: capturing reasoning increases storage and, if done on the hot path, latency; and the richer the capture, the larger the privacy blast radius - which is why the emission-time redaction discipline is not optional. Sampling controls the volume but means some decisions are recorded less fully than others, so what to capture fully is itself a design choice.

The deep caveat is faithfulness. A model can emit a plan or a chain of reasoning that reads convincingly but does not actually correspond to the computation that produced its answer. Treat self-reported reasoning as a claim to be corroborated - against the tool calls actually made, the documents actually retrieved, and the eval of the final output - not as ground truth. Provenance you can verify from independent spans (which document was retrieved, which tool ran under which authority) is trustworthy; narrative the model tells about itself is not, on its own.

With those limits stated plainly, the construction stands: a portable span schema on the OpenTelemetry generative-AI conventions, a provenance layer binding claims to evidence and actions to authority, and a redaction discipline that keeps the telemetry safe. That is what makes an AI decision observable in the strong sense - its internal state reconstructable from what it emitted - rather than merely monitored.

Practitioner Toolkit

Copy-paste, strictly defensive artifacts you can use today. Nothing here attacks a real system.

capture_policy:
  gen_ai.request.model: plain
  gen_ai.usage.tokens: plain
  gen_ai.tool.name: plain
  gen_ai.tool.arguments: hash        # never store raw args
  retrieval.document_ids: plain
  input.text: redact_pii_then_hash
  output.text: sample_raw: 0.05      # keep 5% raw, rest hashed
  eval.quality: plain
  authority.identity: plain
  authority.scope: plain
sensitive_defaults: hash             # unknown fields default to hashed

span = tracer.start('agent.decision')
plan = agent.plan(prompt);            span.set('plan', summarize(plan))
docs = retrieve(prompt);              span.set('retrieval.document_ids', ids(docs))
auth = authz.check(caller, tool, scope)   # explicit authority step
if auth.allowed:
    result = tool.call(args, scope=auth.scope)  # least privilege
    span.set('authority', {id: caller.id, scope: auth.scope})
out = agent.answer(prompt, docs)
for claim in out.claims:
    span.add('provenance', {claim: hash(claim), grounded_by: claim.doc_ids})
span.set('eval.quality', judge.score(prompt, out))
span.end()

Glossary

Semantic telemetry

Telemetry that records the meaning of a system's actions - intent, plan, evidence, tool I/O - rather than only their timing and status.

Decision span

The root span representing one agent decision, with typed child spans for the model call, tools, retrieval, and eval.

OpenTelemetry GenAI conventions

A standardized, vendor-neutral vocabulary of span names and attributes for generative-AI model, tool, and agent operations.

Decision provenance

A record linking each output claim to the evidence that supports it and each action to the authority under which it was taken.

Tool authority

The identity, credential, and scope under which an agent's tool call is made; recording it makes excessive-agency failures auditable.

Faithfulness

Whether a model's stated reasoning corresponds to the computation that actually produced its output; unverified self-reports may not be faithful.

References

1. OpenTelemetry Semantic Conventions for Generative AI Systems
2. NIST AI 100-1, Artificial Intelligence Risk Management Framework (AI RMF 1.0)
3. NIST AI 600-1, Artificial Intelligence Risk Management Framework: Generative AI Profile
4. NIST SP 800-137, Information Security Continuous Monitoring (ISCM)
5. OWASP Top 10 for Large Language Model Applications (2025)
6. Liang et al., Holistic Evaluation of Language Models (HELM)