OpenTelemetry and DB2

Db2 OpenTelemetry in one picture

A user hits a mobile API. The API gateway and Java service create OTel spans and forward traceparent (and optional tracestate) headers. When the service calls Db2—through JDBC, native REST, or another supported attach—Db2 reads that context. For valid sampled traces, Db2 can generate a span for the Db2 unit of work and write it as an extended SMF record. The z/OS Data Gatherer OpenTelemetry Emitter ships those spans through an OTLP collector into your observability backend.

IBM introduced this for Db2 13 (function levels from V13R1M100 upward) via APARs such as PH67971 (distributed tracing support) and related attach APARs (for example IMS). z/OS needs the Data Gatherer emitter support (APAR OA66345 family). Always confirm the PTF list for your release before production enablement.

OTel concepts you need

• Trace — one end-to-end transaction across services
• Span — one unit of work inside that trace (API call, Db2 UOW, etc.)
• Trace context — Trace ID, parent Span ID, flags (sampling)
• Instrumentation — code or middleware that creates spans and injects headers

Db2’s role in the first delivery is primarily inbound: it consumes context other components propagate. Middleware must be OTel-enabled. Db2 alone cannot invent a cloud-side parent span that never existed.

Trace propagation

Trace propagation is how context moves. The W3C Trace Context specification defines HTTP headers and equivalent carrier formats. On REST invokes, those headers ride with the JSON body. On JDBC, the driver and application frameworks must forward context into the Db2 conversation. If sampling says “do not record,” Db2 will not invent full emit traffic for unsampled work—watch DISPLAY OTEL counters to see valid versus sampled parents.

OTel instrumentation and Db2

OTel instrumentation on the distributed side usually means auto instrumentation for Java/Node plus explicit context when calling Db2. On z/OS, CICS, IMS, MQ, and z/OS Connect are also adding OTel-aligned tracing so a request can keep its Trace ID from the edge all the way into Db2 SQL.

Practical checklist for a Java → Db2 pilot:

• Enable OTel on the application and verify spans appear in your backend without Db2
• Apply Db2 and z/OS emitter maintenance
• -START OTEL EMIT(YES) on each data sharing member
• Drive a sampled transaction and confirm DISPLAY OTEL emit counts increase
• Confirm the emitter and collector deliver Db2 spans under the same Trace ID

OTel Db2 records

OTel Db2 records are extended SMF type 1161, subtype 1, span records. Db2 emits one span record per unique Db2 unit of work on a thread when the inbound context is valid and sampled and emission is enabled. These are not a replacement for SMF 101/103 accounting—they are correlation-friendly span payloads for OTel pipelines.

Capacity planning still matters. Emitting spans for every tiny UOW on a huge subsystem increases SMF volume. Use sampling on the distributed side and EMIT controls on Db2. Start with a busy-but-bounded application name before enabling everywhere.

START OTEL, STOP OTEL, DISPLAY OTEL

Command syntax follows IBM’s Command Reference style:

1
2
3
4
-START OTEL EMIT(YES)
-DISPLAY OTEL
-DISPLAY OTEL DETAIL
-STOP OTEL

START OTEL

-START OTEL starts OpenTelemetry processing so Db2 propagates/handles OTel information. EMIT(YES) (default in the documented form) enables writing extended SMF 1161 subtype 1 span records. EMIT(NO) starts processing without emission—useful when validating context acceptance before you accept SMF growth.

STOP OTEL

-STOP OTEL stops all Db2 OTel functions: context handling and span emission. If OTel is already started or stopped, Db2 may ignore a redundant command and issue a message such as DSNW303I indicating OTEL already has that status.

DISPLAY OTEL

-DISPLAY OTEL reports status. Typical fields include STATUS (STARTED), EMIT (YES/NO), RECORDS EMITTED successful and failed counts, and LAST STARTED time. With DETAIL, expect Trace Parent counters (sampling on, valid, invalid) and Trace State counters (valid, truncated, invalid). Rising INVALID counts mean clients are sending broken headers—fix instrumentation before blaming Db2.

1
2
3
4
5
6
7
8
9
10
DSNW300I  !I9A2 DSNWVCM3 DISPLAY OTEL REPORT FOLLOWS:
    STATUS = STARTED
    EMIT   = YES
    RECORDS EMITTED: SUCCESSFUL  =          822
                     FAILED      =            0
    TRACE PARENT:    SAMPLING ON =          903
                     VALID       =          983
                     INVALID     =            0
    LAST STARTED 12:20:50 NOV  4, 2025
    DISPLAY OTEL REPORT COMPLETE.

In data sharing, repeat START and DISPLAY on each member. There is no group-scope shortcut for these commands in the initial support.

OTel monitoring

OTel monitoring is mostly DISPLAY OTEL plus emitter/collector health. Watch successful versus failed emits. Failures can mean SMF or emitter issues downstream of Db2. Correlate with distributed backend dashboards: if cloud spans exist but Db2 child spans do not, check EMIT, sampling, and whether the attach path is supported.

Keep classic Db2 monitoring. OTel explains which business trace waited in Db2; accounting classes still explain why (CPU, lock, I/O). Use both.

OTel and distributed applications

End-to-end success needs three parties: the application (instrumented), Db2 (START OTEL), and z/OS export (Data Gatherer emitter + collector). z/OS Connect, API gateways, and service meshes should forward trace headers unchanged. Native REST services are a natural fit because HTTP already carries W3C headers alongside JSON.

Security note: trace headers are not authentication. You still need SAF auth on REST or JDBC. Avoid putting secrets in tracestate baggage. Sampling policies belong to the platform team so you do not emit every health-check ping into the SIEM-sized backend.

The current Db2 command reference includes START OTEL, STOP OTEL, and DISPLAY OTEL—treat those pages as the authoritative syntax source when your shop’s maintenance level advances and options expand.

Explain It Like I'm Five

Imagine every online order gets a sticker with a tracking number as it moves from the website to the warehouse to the truck. OpenTelemetry is that sticker system. When the order needs something from Db2, the sticker comes along. Db2 can stamp “I worked on this order” onto a postcard (SMF 1161) and send it to the same tracking board the website uses. START OTEL tells Db2 to watch for stickers; EMIT(YES) tells it to send postcards; DISPLAY OTEL counts how many postcards went out.

Exercises

1. Write the commands to start OTel with emission on two data sharing members and verify both with DISPLAY OTEL.
2. Explain the difference between EMIT(YES) and EMIT(NO).
3. Given DISPLAY OTEL DETAIL with high INVALID trace parent counts, list two places you would look first.
4. Describe how a native REST client should send W3C context on an invoke.
5. Name the SMF record type used for Db2 OTel span emission and the z/OS component that emits to OTLP.