CICS Never Starts an OpenTelemetry Trace, So the Caller's Sampler Sets Its Span Volume

CICS TS 6.3 can write an OpenTelemetry span for every task, but it never chooses which tasks. The sampled bit in the caller's W3C traceparent chooses, CICS cannot change it, and the OpenTelemetry SDK default sets it on every request. Here is where the setting that controls your span volume actually lives.

CICS joins a trace only when a caller brings one

IBM's configuration guide states that CICS does not initiate trace context, so context must arrive in incoming requests from clients such as web services, Liberty applications and z/OS middleware (configuring OTel in CICS). The transaction reference adds that if no OTel data is received, CICS does not generate any tracing information (configuration options).

Context reaches a task over five protocols: the Db2 attachment facility, HTTP, IPIC, MRO and IBM MQ (supported protocols). The pages cover 6.3 and the CICS TS beta, and the beta adds scenarios such as RETURN TRANSID and DTP; everything below describes 6.3. IBM's planning guide asks you to enable OTel first in intermediaries such as z/OS Connect, Db2, CICS Transaction Gateway or MQ (planning considerations).

Setting OTELTRACE to YES makes every transaction eligible

Three switches control the behaviour. OTELTRACE is a SIT parameter that defaults to NO and overrides everything below it; each transaction then carries OTELPROP (PROPONLY or NOPROP) and OTELEMIT (TASKEND or NOEMIT) (configuration options). A span data record is produced only for PROPONLY with TASKEND, and only if the sampled flag is set on in the inbound context.

The defaults are the detail to plan around. After a DFHCSDUP UPGRADE, every transaction definition carries OTELEMIT set to TASKEND and OTELPROP set to PROPONLY, so IBM notes that transactions are automatically set to produce span data records once OTELTRACE is YES (configuring OTel in CICS). Those records are SMF type 1159, and an IBM z/OS emitter formats them for an observability backend, directly or through an OTel collector.

The sampled bit is a hint in W3C and binding in CICS

The W3C Trace Context Recommendation defines one flag, sampled, which denotes that the caller may have recorded trace data (W3C Trace Context). It calls the trace flags recommendations from the caller, and one of its three reasons is that different load between caller and callee might force the callee to downsample. A component may change the sampled flag as long as it also updates parent-id.

CICS updates the parent ID at every task: the trace ID stays the same and each task gets a new span ID (supported protocols). The standard therefore leaves CICS room to downsample. CICS 6.3 does not take it: IBM states that CICS does not provide a mechanism to dynamically change the sampling flag, and that context sent from CICS to other systems includes the sampled flag (planning considerations). The decision made upstream is the one Db2 and MQ see next.

The OpenTelemetry SDK default samples every root span

Whoever creates the root span sets that bit. The W3C text says a component that made a definitive recording decision should reflect it in the sampled flag (W3C Trace Context). In the OpenTelemetry SDK specification the default sampler is ParentBased(root=AlwaysOn), and AlwaysOn returns RECORD_AND_SAMPLE always (OTel tracing SDK). The OTEL_TRACES_SAMPLER environment variable defaults to the same thing, parentbased_always_on (OTel environment variables).

Set the three documents side by side and the chain is short. A front end running an SDK with no sampler configured samples every request it originates and marks each one sampled. Every CICS transaction those requests reach over the five protocols, left at its defaults, then writes an SMF 1159 record at task end, because CICS cannot sample them down: per transaction it is all sampled tasks or none.

IBM's planning guide does tell you to consider head-based sampling to limit the volume of requests (planning considerations). The setting that does it sits in the caller's environment, owned by a team that may never read an SMF report.

One record per task, with two exceptions IBM names

A span starts when a task begins and ends when it completes. The CICS-MQ adapter is the exception: for tasks started by the trigger monitor CKTI, CICS picks up context from an MQ message at the start of each unit of work and emits a span at its end, so one task that gets several traced messages emits several spans (supported protocols).

Long-running tasks are the other case. IBM suggests that regions used mainly for them might not benefit from span emission at task termination, and that propagation alone still keeps the trace intact (planning considerations).

Agree the sampler before you set OTELTRACE to YES

Ask the team that owns the trace root which OTEL_TRACES_SAMPLER it runs. If the answer is the default, agree a ratio with them: parentbased_traceidratio takes a probability between 0 and 1 in OTEL_TRACES_SAMPLER_ARG (OTel environment variables). Where you need no spans, set OTELEMIT to NOEMIT and keep PROPONLY, because IBM says propagation should be enabled in all regions to keep the trace whole (planning considerations).

SET TRANSACTION changes both attributes without restarting the region (configuring OTel in CICS). Start with a few regions, as IBM recommends, and compare the SMF 1159 record count with the request rate at the trace root. If the two rise and fall together, the caller is sampling everything.