Spans, traces, and context propagation in CICS TG
Context propagation in OpenTelemetry (OTel) is the process of passing trace context information between the different components or systems that are involved in a distributed application transaction. By understanding this flow or journey of the application, you can identify performance bottlenecks and pinpoint the location of a problem.
CICS TG and client applications using the CICS TG SDK can be configured to participate in OTel tracing by propagating context and optionally producing a span data record when a task finishes. Propagating context enables CICS TG and client applications to link their spans with other parts of the transaction, maintaining tracing continuity across the distributed system.
Spans and traces
OTel uses traces and spans to track the journey of an application across components. Traces are collections of spans that represent the entire journey of a distributed application transaction across multiple components. Each component contributes to the trace by emitting a span.
Each span contains the following mandatory information:
Span Name: A descriptive span name helps convey what the span represents—such as the name of a CICS TG application or a specific transaction—making it easier to understand the context of the traced operation.
Span Context: The span context uniquely identifies a span within a trace and carries the necessary identifiers and options required to propagate the trace across components and systems. It is passed from parent spans to child spans, ensuring continuity and consistency of the distributed trace throughout the entire transaction flow.
- Trace ID: A unique identifier for the entire trace, consistent across all spans within that trace. The trace ID is 16 bytes in size and is typically represented as 32 UTF-8 characters. It enables all related spans to be linked together, allowing the full journey of a distributed transaction to be traced—across systems, including CICS TG on z/OS.
- Span ID: A unique identifier for each individual span within the trace. This ID is used by child spans as the parent ID, establishing hierarchical relationships between spans and building the trace structure.
- Trace Flags: A one-byte (8-bit) field that carries options related to the trace. For example, it includes a sampling bit that indicates whether the trace should be recorded and exported. This helps control the volume of telemetry data collected.
Parent Span: The parent span ID identifies the parent of a given span, or is null if the span is the root span. This ID establishes the hierarchical relationship between spans within a distributed trace.
Span Kind: Indicates the role of the span within the trace, such as SERVER or CLIENT. Since CICS TG typically acts as middleware for transactions, it usually issues server spans.
Start Timestamp: The time when the operation represented by the span began. It is used to measure the duration of the operation and to establish the order of events.
End Timestamp: The time when the operation represented by the span ended. Together with the start timestamp, it defines the span’s duration.
Attributes: An optional component of the trace context that carries vendor-specific information as a list of key-value pairs. These attributes enrich the trace data, enabling better correlation, debugging, and performance tuning.