Trace an AI agent as a connected sequence of meaningful operations: the incoming workflow, each model interaction, tool execution, and retrieval or data access when those are distinct work worth diagnosing. Use the dedicated OpenTelemetry GenAI semantic-conventions repository for current operation names and fields; treat names in the older GenAI attribute registry as migration context, not as a guarantee that those fields remain current.
1. Map the agent’s work before adding spans
Start by sketching one real execution from request entry to response. Mark operations that take meaningful time, cross a process or service boundary, or would help explain a failure, retry, latency spike, or unexpected result. OpenTelemetry describes spans as executions of operations, recommends spans for significant operations with duration, and favors events for point-in-time occurrences. Its guidance cautions against spans for short local operations without an out-of-process call unless there is a specific tracing reason. See Trace semantic conventions and How to write semantic conventions.
As an Amazon Associate I earn from qualifying purchases.
- Request or workflow: Represent the incoming request or orchestration workflow when it provides a useful boundary for understanding the end-to-end execution.
- Model interaction: Record each meaningful model operation as its own operation, especially when an agent makes multiple calls, retries, or uses different models.
- Tool execution: Represent a tool’s actual work separately from the model interaction that requested it. Preserve enough trace context to connect the request for a tool with its execution and result.
- Retrieval or data access: Trace retrieval when it is a distinct operation with diagnostic value—for example, when its latency or failure could explain the agent’s behavior. Existing database or client instrumentation may already cover some of this work.
- Response: Keep the ending of the workflow interpretable, including relevant errors or completion status, without creating spans for every small internal function.
This is a logical shape, not a required fixed tree. Let the agent’s actual boundaries and the instrumentation already present determine which operations need spans. A trace should help an operator see where time was spent and which operation failed, without obscuring the path in low-value detail.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →2. Use the dedicated GenAI conventions as the naming source
The current source of truth is OpenTelemetry’s GenAI semantic-conventions repository. It describes conventions for GenAI clients, MCP, and provider-specific integrations, including spans, metrics, and events. Its Markdown documentation is generated in part from YAML model definitions, so consult the repository’s current definitions rather than relying on a copied field list.
#1 Best Overall
The older GenAI attribute registry explicitly says its GenAI attributes have moved to the dedicated repository. It remains useful for understanding earlier instrumentation and migration questions, but its labels and status should not be assumed to be the latest recommendations. Before shipping, confirm the exact operation names, attributes, and stability status in the convention version supported by the instrumentation you deploy.
3. Decide what to record for each operation
For every model, tool, or retrieval operation, first check the matching current convention. Record fields that make the operation identifiable and useful to correlate; capture message or payload content only when there is a justified debugging need and an approved handling policy.
| Operation | What the trace should help answer | Fields to verify in the current convention |
|---|---|---|
| Model interaction | Which operation ran, with which provider or model, and what usage information is available? | Operation name; provider and model identifiers; request and response-related fields; usage fields. Confirm the current names and availability in the deployed convention version. |
| Tool execution | Which tool actually ran, what work did it perform, and how does it relate to the model’s tool request? | Current tool and operation definitions; any supported fields for tool-call arguments or results. Keep the causal relationship visible, but avoid exposing sensitive content unnecessarily. |
| Retrieval or data access | Was retrieval a distinct step, and where did time or failure occur? | Current retrieval or data-access definitions and the fields supported by the relevant instrumentation. Coordinate with existing database or client spans. |
The legacy registry illustrates earlier field families such as gen_ai.operation.name, provider and model fields, input and output messages, gen_ai.tool.call.arguments, gen_ai.tool.call.result, and token usage. These are examples of what earlier conventions represented—not a current field prescription. Check each proposed name and its status in the dedicated repository before using it in instrumentation, dashboards, or queries.
4. Treat prompts, tool data, and retrieval text as sensitive
Message content is not just telemetry metadata. Inputs and outputs may contain personal information; system instructions, retrieval queries, tool arguments, and tool results can also expose private or confidential material. The legacy registry’s sensitive-content notes call out these risks and note that instrumentation may provide filtering or truncation options.
- Choose deliberately whether to capture content at all; do not make full prompt and response capture an accidental default.
- Prefer the minimum content needed to diagnose the use case. Where supported, use instrumentation filtering or truncation before data leaves the application.
- Document what is captured and apply your organization’s access, retention, and privacy requirements to traces and downstream systems.
- Review model, tool, and retrieval data separately: omitting chat messages alone may not protect secrets that appear in tool arguments or results.
5. Pin a convention version and manage changes
Convention names and support can evolve. OpenTelemetry’s semantic convention version-selection guidance recognizes the gen_ai domain and provides settings for selecting a version and experimental conventions. Check what your deployed instrumentation actually supports, then make the intended version and experimental-field choices explicit in configuration and upgrade practice.
When changing versions, review dashboards, alerts, queries, and any systems that consume trace attributes. Treat a convention upgrade as a schema change: verify which fields are added, changed, or no longer emitted before relying on them for operational decisions. Do not enable experimental conventions by assumption; decide whether their potential value justifies tracking an evolving schema.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.6. Validate traces against real agent paths
OpenTelemetry’s convention-authoring guidance recommends prototyping conventions in real instrumentations and assessing feasibility, overhead, and interaction with other instrumentation layers. Apply that discipline to the agent rather than judging the design by attribute presence alone.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minute- Run representative executions, including a normal response, a failed operation, a retry, and a tool-using path.
- Inspect each trace from entry point to completion. Check that significant model, tool, and retrieval work is visible and connected in a way that explains the execution.
- Confirm that the selected convention names and fields match the version configured for the instrumentation.
- Compare the trace with existing client, server, and database instrumentation. Resolve confusing duplicate spans and gaps where an important operation is not represented.
- Assess data availability and overhead, including the effect of any content filtering or truncation you enabled.
Common names and attributes make spans easier to interpret consistently across codebases and to correlate across services written in different languages. That benefit depends on choosing a convention version deliberately and recording enough of the operation—not necessarily its full content—to make the trace useful. See the OpenTelemetry semantic conventions overview.
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
