> ## Documentation Index > Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Span Name and Context > Guidance on naming spans and explaining span context and its components trace_id span_id trace_flags trace_state for effective distributed tracing and propagation Hello, span gurus. In this lesson we focus on span names and span context — two small but critical pieces that make distributed tracing useful. First we’ll cover naming guidance and how to capture important details as attributes. Then we’ll explain span context (the immutable metadata that travels between processes) and its components: trace\_id, span\_id, trace\_flags, and trace\_state. ## Span names Span names are the human-readable labels you give to each span. They communicate, at a glance, what an operation represents (for example, `GET /home`, `processPayment`, or `validateUserInput`). Clear, consistent names make traces easier to read than raw IDs or hex strings and help you spot patterns and failures quickly. Best practices * Be consistent: adopt a small set of naming patterns across services (verb-object is a simple and effective convention, e.g., `process payment`, `send invoice`, `render ad`). * Be generic: keep the span name focused on the operation, not request-specific details (put those in attributes). * Use automatic instrumentation for common operations (HTTP, DB). Reserve custom spans for unique business logic or important internal steps. Common examples of span names: * `call httpbin` (external endpoint used in demos) * `processPayment` * `validateUserInput` * `getProducts` * `postOrders` * `getProduct` * `convertCurrency` * `getCart` * `listRecommendations` * `listAdsByCategory` * `getLoyaltyStatus` Keep span names generic and stable. Put request-specific details (URLs, IDs, amounts) into span attributes rather than the span name. The image illustrates the concept of naming custom spans, differentiating between auto-instrumentation (handling standard operations like HTTP requests and DB queries) and custom spans (capturing unique business logic), with a naming convention of "verb object". ## Well-named business spans and attributes Use a concise, generic span name for the operation and record request-specific data as attributes (key-value pairs) attached to the span. Backends may index frequently queried attributes, so choose and document the attributes you rely on. Example patterns: * Name: `processPayment`\ Attributes: `payment.method`, `payment.amount`, `payment.currency` * Name: `validateUserInput`\ Attributes: `user.id`, `input.type`, `validation.result` * Name: `getProducts` or `postOrders`\ Attributes: `http.method`, `http.url`, `http.route`, `db.statement` (as applicable) The image is a table titled "Well Named Business Spans and Their Context," showing examples of span names, their representations, and associated attribute captures. It includes examples such as calling httpbin, processing payments, and validating user input. ## Span context (the metadata that moves) Span context is the immutable bundle of metadata attached to every span. It is the serialized object that is propagated between services and is essential for linking spans into a single distributed trace. Key fields | Field | Purpose | Typical format / example | | ------------- | --------------------------------------------------- | ----------------------------------------------------------------- | | `trace_id` | Links all spans in a single trace | `32-character hex` — e.g., `089f12de04e7927b486956fda8c89d95` | | `span_id` | Identifies this specific span within the trace | `16-character hex` — e.g., `8c18abb071c362d0` | | `trace_flags` | 8-bit field controlling sampling behavior | `00` or `01` (sampled) | | `trace_state` | Optional vendor-specific metadata (key=value pairs) | Comma/semicolon-separated list, e.g., `vendor1=val1,vendor2=val2` | A representative (illustrative) span context (JSON-style for clarity): ```json theme={null} { "context": { "trace_id": "089f12de04e7927b486956fda8c89d95", "span_id": "8c18abb071c362d0", "trace_state": [ "f4fe05b2-bd92206c@eg=fw4;3;abf102d9;c4592;0;0;2ee;5607;2h01", "apmvendor=boo", "foo=bar", "ot=rv:6e6d1a75832a2f" ], "trace_flags": "0x01" } } ``` Note: the HTTP propagation format is defined by the W3C Trace Context spec (for example, `traceparent` and `tracestate` headers). The JSON above is illustrative — the essential idea is that the trace id, span id, flags, and optional trace\_state are what get propagated between processes. Exam tip: When asked "which part moves across process boundaries?", the answer is the span context (trace\_id, span\_id, trace\_flags, and trace\_state), typically carried in headers during propagation. ## Trace ID Trace ID links all spans in a single trace and remains the same for the life of that trace. * Size & format: 16 bytes (128 bits), typically represented as a 32-character hexadecimal string (for example, `089f12de04e7927b486956fda8c89d95`). * Purpose: allows trace tools to map a request path across services, databases, proxies, and more. * Immutability: the trace ID does not change during the trace — if it changes, you are observing a different trace. The image explains the size and format of a Trace ID, highlighting its uniqueness, 16-byte length in a hexadecimal format, and its purpose in mapping requests through systems. The image is a slide titled "Trace ID: Scope and stability," explaining that a Trace ID can cover multiple services and locations, and is immutable once created. ## Span ID Span ID uniquely identifies a single span (one operation) within a trace. * Size & format: 8 bytes (64 bits), typically represented as a 16-character hexadecimal string (for example, `8c18abb071c362d0`). * Scope: unique within its trace (two spans in different traces can have the same span ID). * Purpose: enables reconstruction of parent-child relationships, timing charts, and waterfall views. * Parent relationships: a child span carries the span ID of its parent in its context; the root span has no parent span ID. The image is an informational slide about Span ID Uniqueness, detailing the uniqueness of Span IDs within a trace, their length and format as a 16-character hexadecimal string, and a placeholder for purpose information. ## Trace flags Trace flags are an 8-bit field included in every trace context; they are primarily used for sampling decisions. * Size & format: 8 bits (1 byte), commonly shown as two hex characters (e.g., `00`, `01`). * Example values: `00` (no flags set), `01` (sampled). * Common usage: when the sampled flag (`0x01`) is set, the trace is a candidate for export, subject to SDK/exporter configuration. Example: access trace flags in OpenTelemetry Python ```python theme={null} # Access the span's context and print TraceFlags (example with OpenTelemetry Python API) trace_flags = span.get_span_context().trace_flags print(f"[main] TraceFlags: {trace_flags:#04x}") # formatted as hex, e.g., 0x01 ``` Output: ```text theme={null} [main] TraceFlags: 0x01 ``` The image is an informational graphic about TraceFlags, which are 8-bit fields controlling tracing behavior related to sampling and future use cases. The image is a slide about "TraceFlags — Size & Format," explaining its size (8 bits), inclusion in trace context propagation, hexadecimal representation, and example values like "00" for no flags set and "01" for sampled flag set. ## TraceState TraceState carries optional, vendor-specific metadata as a list of key-value entries. It allows multiple tracing systems to cooperate without overwriting each other’s metadata. * Format: comma- or semicolon-separated list of `key=value` entries, e.g., `vendor1=val1,vendor2=val2`. * Size rules: keys must be unique; the overall `tracestate` length is limited (for example, 512 characters per the W3C Trace Context spec). * OpenTelemetry note: `ot=` entries are reserved for OpenTelemetry; instrumentation libraries should not alter `ot=` entries and should use their own keys. Illustrative `tracestate` entries: ```plaintext theme={null} ot=p:8;r:62 ot=foo:bar;k:1:13 f4fe05b2-bd92206c@dt=fw4;3;abf102d9;c4592;0;0,apmvendor=boo,foo=bar tenant1@vendor1=abc123,tenant2@vendor2=xyz789 ``` Example JSON-style representation (for clarity): ```json theme={null} { "context": { "trace_state": [ "f4fe05b2-bd92206c@eg=fw4;3;abf102d9;c4592;0;0;2ee;5607;2h01", "apmvendor=boo", "foo=bar", "ot=rv:6e6d1a75832a2f" ] } } ``` Do not modify reserved `ot=` entries in `trace_state`. Use vendor- or system-specific keys for your additional metadata to avoid clobbering other systems' data. ## Parent ID, root, and children * Root span: the first span in a trace; it has no parent span ID (parent is unset or null). * Child span: a span created by another span; it stores the parent span ID in its context to form the parent-child link. * Parent ID rules: * Parent ID always refers to another span within the same trace. * Parent ID is immutable for that span (does not change after creation). These parent-child links let tools build trace trees, waterfall charts, and dependency maps. The image is a presentation slide titled "Parent IDs: Traces into Maps and Timelines," focusing on the purpose of enabling visualizations like trace trees, waterfall charts, and dependency diagrams, with icons representing each type of visualization. The image is a slide titled "Parent ID Rules: Same Trace, Immutable," explaining that a Parent ID always refers to another Span ID within the same Trace ID and does not change after the span is created. ## Recap * Span name: concise description of the operation (e.g., `processPayment`). Keep it generic and put request-specific details into attributes. * Span context: the metadata bundle that travels with the span (`trace_id`, `span_id`, `trace_flags`, `trace_state`). This is what propagation carries across process boundaries. * Trace ID: 16 bytes (128 bits), represented as a 32-hex-character string; same across all spans in a trace. * Span ID: 8 bytes (64 bits), represented as a 16-hex-character string; unique per span within a trace. * Parent span ID: the span ID of the parent that created this span; used to reconstruct the trace tree. * Trace flags: an 8-bit field used primarily for sampling; `0x00` = not sampled, `0x01` = sampled. * TraceState: optional vendor metadata as key-value pairs; used to pass additional context in multi-vendor environments. The image is a summary of OpenTelemetry Span and Trace fundamentals, detailing Span Name, Span Context, Trace ID, and Span ID, along with their characteristics and examples. The image is a slide summarizing the fundamentals of OpenTelemetry span and trace, including concepts like parent span, child span, trace flag, and trace state with examples. That's it for this section.