Span

The Span Name is a human-readable identifier for the operation, such as call_tool:get_weather or api_request:POST /v1/chat/completions. It should be descriptive and consistent to enable effective aggregation and filtering in observability dashboards. The Operation itself is the timed execution block the span represents.

The Span Context contains the essential identifiers for distributed tracing:

• Trace ID: A globally unique 16-byte identifier shared by all spans in a single request's journey.
• Span ID: A unique 8-byte identifier for this specific span.
• Parent Span ID: The ID of the span that directly invoked this operation, establishing causality. This context is propagated via headers (e.g., traceparent) to external APIs, enabling Trace Correlation across service boundaries.

Spans are fundamentally defined by time. Two precise timestamps are recorded:

• Start Timestamp: The nanosecond-precision UTC time when the operation began.
• End Timestamp: The time when the operation completed (or failed). The Duration is calculated as (End Timestamp - Start Timestamp). This is the primary data point for performance analysis, allowing engineers to calculate metrics like average latency, P95, and P99 for tool calls.

Span Attributes are key-value pairs that provide descriptive metadata about the operation. For tool call instrumentation, critical attributes include:

• tool.name: "stripe_create_charge"
• http.method: "POST"
• http.status_code: 429
• `api.endpoint": "/v1/charges"
• `error.type": "RateLimitExceeded" Attributes enable powerful slicing and dicing of trace data, answering questions like "Show me all failed calls to the payment API."

The Span Status succinctly conveys the result of the operation. It consists of a Status Code and an optional Status Message.

• UNSET: The default; the span status is not known.
• OK: The operation completed successfully.
• ERROR: The operation terminated with an error. A status of ERROR is a primary filter for identifying failing tool calls in monitoring systems, distinct from (but often accompanied by) error-related attributes.

Span Events are timestamped logs attached to a span, representing significant moments during the operation's lifecycle. Each event has a name and optional attributes. For a tool call, typical events include:

• "retry.attempt" (with { "attempt.number": 2 })
• "cache.hit"
• "exception" (with { "exception.type": "TimeoutError", "exception.stacktrace": "..." }) Events provide a granular, sequential narrative within the span, crucial for debugging complex failures.

A Trace is the complete end-to-end record of a single request or operation as it flows through a distributed system. It is composed of a collection of Spans, which represent the individual steps. For an agent executing a task, a trace would encapsulate the entire workflow, from the initial user prompt, through internal planning steps, to each external tool call, and finally to the agent's synthesized response. Traces provide the holistic context needed to understand performance bottlenecks and error propagation.

Distributed Tracing is the methodology and practice of observing requests as they propagate across service boundaries. In agentic systems, this involves instrumenting code to generate Spans for each logical operation and using Trace Correlation to stitch these spans together, even when they cross network calls to external APIs. This technique is critical for debugging complex, multi-step agent workflows where a failure in one tool can cascade and cause the entire task to fail.

Span Attributes are key-value pairs of metadata attached to a Span that provide descriptive context about the operation. For a tool call span, essential attributes include:

• tool.name: "google_search"
• http.method: "POST"
• http.status_code: 200
• agent.session_id: "sess_abc123"
• llm.vendor: "anthropic" These attributes enable powerful filtering, grouping, and analysis in observability backends, turning raw timing data into actionable insights.

Span Events are timestamped, structured log records attached to a specific point within a Span's lifetime. They capture significant moments during an operation that are not separate sub-operations. For a tool call, key events might be:

• "retry.initiated" (with attempt number)
• "cache.miss"
• "rate.limit.hit"
• "error" (with error message) Unlike creating a new child span for every minor occurrence, events are a lightweight way to annotate a span's timeline with diagnostic details.

Trace Correlation (or Context Propagation) is the mechanism that enables Distributed Tracing. It involves passing a unique Trace ID and the current Span ID across process and network boundaries, typically via HTTP headers (e.g., traceparent). When an agent calls an external tool API, it injects this context into the request. If the external service is also instrumented, it will create child spans linked to the agent's trace, allowing visualization of the entire call chain. Without correlation, spans remain isolated islands of data.

OpenTelemetry Instrumentation refers to libraries and agents that automatically generate Spans, metrics, and logs from application code, adhering to the vendor-neutral OpenTelemetry standard. For tool calls, OTel provides instrumentation for common HTTP clients, gRPC, and database drivers. This auto-instrumentation eliminates the need for manual span creation boilerplate, ensuring consistent, high-quality telemetry data that can be exported to any compatible backend like Jaeger, Datadog, or Grafana.