OpenTelemetry Span Builder

A span is the fundamental unit of work in OpenTelemetry distributed tracing. It represents a single operation — an HTTP request, a database query, a function call — with a start time, duration, status, and a set of key-value attributes. Spans are grouped into traces by sharing the same Trace ID. A trace forms a directed acyclic graph (DAG) of spans that shows the full path of a request through your system.

A Trace ID (128-bit / 32 hex chars) uniquely identifies an entire distributed trace — all the spans that belong to the same request journey across services share one Trace ID. A Span ID (64-bit / 16 hex chars) uniquely identifies a single span within that trace. The Parent Span ID links a child span back to its parent, forming the trace hierarchy. Root spans have no Parent Span ID.

INTERNAL: An internal operation within the same service (e.g., a helper function). SERVER: The span covers a request received by a server (e.g., an HTTP handler). CLIENT: The span covers an outgoing request to a remote service (e.g., an HTTP client call or DB query). PRODUCER: The span covers a message being sent to a queue or messaging system. CONSUMER: The span covers a message being received and processed from a queue. Span Kind affects how tracing UIs display call graphs and calculate latency attribution.

OTLP (OpenTelemetry Protocol) is the native wire format for OpenTelemetry data. It uses Protocol Buffers over gRPC or JSON over HTTP. OTLP is vendor-neutral and supported by all major observability backends: Jaeger, Zipkin, Datadog, Grafana Tempo, Honeycomb, New Relic, AWS X-Ray, and more. Using OTLP means you can switch backends without changing your instrumentation code — just point the exporter at a different endpoint.

Attributes are key-value pairs attached to a span that describe the context of the operation — e.g., http.method='GET', db.system='postgresql', http.status_code=200. They use semantic conventions defined by the OpenTelemetry specification for consistency across tools. Events are timestamped log-like records attached to a span, useful for marking a specific point in time within the span's duration — e.g., 'cache.hit' or 'payment.validated'. Unlike attributes, events capture something that happened at a specific moment.

UNSET (0): The default status. The span completed without an explicit status being set — this does not necessarily mean success. OK (1): The operation completed successfully and the developer explicitly marked it as OK. ERROR (2): The operation failed. When set to ERROR, you should also provide an error message. Most backends highlight ERROR spans in red for easy identification. Do not set OK unless you explicitly want to override the default; leave as UNSET for spans where status is not meaningful.