Emit enough context to explain a run.

Required identity

Every run must be correlated to a stable service identity and environment. Use standard OpenTelemetry resource attributes where possible.

service.name = "your-agent-service"
deployment.environment = "production"
tracey.agent.id = "your-agent-service"
tracey.run.id = "run-123"

Root span

Create one root span for the complete agent execution. Record start and end time, outcome, and the trace ID. Do not put raw prompts or responses into attributes by default.

span.name = "agent.run"
tracey.outcome = "success | failure | timeout | cancelled"
tracey.prompt.version = "support-v3"
tracey.error.class = "tool_timeout"

Child spans

Preserve the causal path with child spans for model calls, tools, MCP, retrieval, handoffs, and side effects.

agent.route
gen_ai.chat
tool.call
mcp.request
retrieval.query
agent.handoff
agent.result

Useful measurements

Emit measurements that support diagnosis and cost analysis without exporting sensitive content.

• Input and output token counts
• Duration and time-to-first-token
• Retry count and fallback selection
• HTTP status and dependency outcome
• Prompt or policy version
• Estimated cost when pricing metadata is available

Completeness checklist

Before connecting production, generate a known success, failure, timeout, tool error, and fallback run. Confirm each appears as a connected trace with the expected outcome and evidence.

The contract is intentionally additive. Start with root identity and outcome, then instrument the child spans that matter most for your agent.