What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Trace an agent by recording its meaningful operations—such as the request workflow, model calls, tool execution, and retrieval—as connected spans, then use the current OpenTelemetry GenAI conventions to name and describe those operations consistently. Before adding prompt or result content, decide what is safe to capture; before choosing field names, check the conventions version supported by the instrumentation you deploy.
What an agent trace should show
A useful trace lets an engineer follow a request through the work that matters: where time was spent, which operation failed, and how model and tool activity fit into the workflow. OpenTelemetry describes spans as executions of operations and recommends using spans for significant operations with duration; point-in-time occurrences are generally better represented as events. Its guidance also cautions against spans for short local operations that do not involve out-of-process calls unless there is a specific tracing reason. See OpenTelemetry’s trace semantic conventions and convention-authoring guidance.
Start by sketching the runtime path rather than instrumenting every function. A typical trace might contain:
- The incoming request or top-level agent workflow.
- A model operation, with any distinct model interactions represented separately when that distinction helps diagnose latency, errors, or behavior.
- Tool execution, such as an API call or other out-of-process action.
- Retrieval or other data access when it is a distinct operation worth diagnosing.
- The final response operation, if it is a meaningful step in your system.
This is a logical shape, not a requirement to create a span for every item or to use a particular parent-child layout. Use the boundaries that reflect your actual execution and preserve the causal relationship between a model’s tool request and the corresponding tool work. Avoid spans for trivial internal steps that add noise without helping an operator.
#1 Best Overall
Use the dedicated GenAI conventions as the source of truth
OpenTelemetry’s older GenAI attribute registry says that GenAI attributes have moved to a dedicated OpenTelemetry GenAI semantic conventions repository. That repository covers conventions for GenAI clients, MCP, and provider-specific integrations; its Markdown documentation is generated in part from YAML model definitions. Consult the dedicated repository for current operation names, fields, stability information, and migration guidance.
The legacy GenAI registry remains useful as migration context and a glossary of the kinds of information instrumentation has represented. It is not evidence that an old field name or stability label is still the current recommendation. In particular, do not copy a legacy name into production merely because it appears in an older example.
Choose span boundaries and fields for model and tool work
For each model interaction and tool operation, consult the current convention definition that matches the kind of operation and instrumentation you use. The fields you need should answer operational questions, without collecting more content than the use case warrants.
| Operation | What to establish from the current convention | Why it helps |
|---|---|---|
| Model interaction | Operation name; provider and model identifiers; applicable request and response fields; usage information. | Distinguishes model work, helps compare behavior across providers, and can make latency, failures, and usage easier to investigate. |
| Tool execution | Operation and tool identifiers, plus any applicable request, argument, or result fields. Preserve the relationship to the model interaction that initiated it. | Shows whether a failure or delay occurred in the agent’s model work or in an external action. |
| Retrieval or data access | The current applicable operation and retrieval fields, if retrieval is a distinct operation in your system. | Separates time and errors spent fetching context from time and errors spent on model or tool work. |
The older registry includes examples of 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. Treat these as legacy vocabulary to help locate the relevant concepts—not as a current field checklist. Confirm each exact name and its status in the dedicated conventions and in the instrumentation version you deploy. The legacy registry also identifies message content and tool or retrieval data as potentially sensitive: see its GenAI attribute notes.
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 →Make content capture an explicit decision
Prompts and completions are not the only sensitive parts of an agent trace. System instructions, tool arguments and results, and retrieval queries can expose personal, private, or confidential information. Decide what your organization permits before enabling content capture, and document the decision so operators know what traces may contain.
- Capture only the content needed to diagnose the use case; prefer metadata or limited context when full text is unnecessary.
- Use filtering or truncation options where the instrumentation provides them, and verify what those controls omit or retain.
- Apply your organization’s access and retention requirements to traces containing content, not just to application logs.
- Review failure paths as well as successful paths: errors and retries may record different request or result data.
The legacy registry notes that instrumentations may provide message filtering or truncation, but availability and behavior are instrumentation-specific. Confirm the controls in the deployed library rather than assuming a convention itself redacts data.
Pin the convention version and manage upgrades
Convention names and development-stage fields can change. OpenTelemetry’s semantic convention version-selection guidance recognizes a gen_ai domain and provides settings for selecting a version and experimental conventions. Check how your deployed instrumentation selects and supports those settings; the existence of a convention does not establish that a particular library version implements it.
- Record the instrumentation library and GenAI convention version used by each service.
- Check the current dedicated GenAI repository and the library’s support notes before adopting a field or enabling development-stage conventions.
- Plan convention upgrades deliberately. Update dashboards, queries, and downstream consumers to account for schema changes rather than assuming names and meanings remain fixed.
- Keep the selected version and upgrade decision available to the people who interpret traces.
Validate traces against real agent paths
OpenTelemetry’s convention-authoring guidance recommends prototyping conventions in real instrumentations and assessing feasibility, overhead, and interactions with other instrumentation layers. Apply that practice to your agent before relying on its traces in production.
Best Value
- Run representative successful, failed, retried, tool-using, and retrieval-using requests.
- Inspect each trace to see whether its operations and causal relationships are understandable, and whether it answers where time was spent and what failed.
- Check whether existing client, server, and database instrumentation already records the same work. Resolve confusing duplication or missing boundaries.
- Measure the overhead and confirm that the required trace data is available to the people and systems that need it.
Common semantic names and attributes make traces easier to interpret consistently across codebases and to correlate across services written in different languages. That is the practical payoff of using conventions rather than inventing a separate field vocabulary for every agent. See the OpenTelemetry semantic conventions overview and its trace conventions.
Quick Recap
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.
