PH67971: DB2 FOR Z/OS OPENTELEMETRY DISTRIBUTED TRACING SUPPORT

Obtain the fix for this APAR.

APAR status

• Closed as new function.

Error description

• Db2 for z/OS Distributed Tracing and OpenTelemetry support
  (Epic 32101)
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED: All users of Db2 for z/OS                    *
  ****************************************************************
  * PROBLEM DESCRIPTION: This APAR provides an enhancement to    *
  *                      Db2 for z/OS, which adds OpenTelemetry  *
  *                      Distributed Tracing support for         *
  *                      inbound connections to Db2.             *
  *                      Db2 Epic: 32101                         *
  ****************************************************************
  OpenTelemetry (OTel) is a collection of APIs, SDKs, and tools,
  which can be used to instrument, generate, collect, and export
  telemetry data to help site reliability engineers (SRE)
  analyze the performance and behavior of their software.
  
  Without OTel, operational management is dependent on multiple
  system programmers and subject matter experts (SMEs) to
  identify and perform all diagnostic and tuning activities.
  There is very limited ability for a non-specialist SRE or
  application centric user to perform basic problem
  identification and determination activities due to the lack
  of OTel observability support on the Db2 for z/OS platform.
  
  Keyword: OPENTELE/K.
  Fix Category: IBM.Function.OpenTelemetry
  

Problem conclusion

Temporary fix

Comments

• OpenTelemetry (OTel) is a collection of APIs, SDKs, and tools
  that site reliability engineers (SRE) can use to instrument,
  generate, collect, and export telemetry data to help analyze
  the performance and behavior of their software.
  
  OTel consists of three categories of telemetry data:
  metrics, logs, and traces.
   - Metrics provide runtime measurements of a system.
   - Logs provide a recording of events.
   - Traces track the flow of an application through a system.
  
  This APAR enhances Db2 to add support for OTel traces,
  based on the World Wide Web Consortium (W3C) trace context
  specification.  Specifically, this APAR delivers Db2
  enhancements to:
   - Accept "inbound" W3C based OTel trace context propagation
     from OTel enabled Db2 application environments
   - Optionally report ("emit") the Db2 activity for a OTel
     enabled Db2 application as Db2 OTel trace span records.
   - For valid and sampled trace context values, Db2 will
     generate and "emit" an OTel trace span record for each
     unique Db2 unit of work on a thread.
   - Db2 will "emit" (write) OTel trace span record data using
     a new, extended SMF record type 1161 format.  Db2 OTel
     span records written as extended SMF record type 1161
     can be read and processed by new functionality added to
     the IBM z/OS Data Gatherer component by APAR OA66345.
  
  With this APAR, Db2 can support "inbound" OTel trace context
  propagation and span record generation the following OTel
  enabled Db2 for z/OS application environments:
   - Db2 for z/OS native REST services
   - Db2 JCC type-4 Client driver (JDBC Type-4)
   - CICS-Db2 Attachment Facility (CICS-Db2 Attach Facility)
   - CICS Liberty-JDBC type-2 (Db2 RRSAF attach facility)
   - IMS-Db2 Attachment (ESAF/IMS Db2 attach facility)
   - IMS-Db2 Java Adapter-JDBC type-2 (Db2 RRSAF attach
     facility)
   - z/OS Connect-Db2 Rest service (HTTP header)
  
      **** IMPORTANT NOTE ****
  This APAR only provides the support for the Db2 for z/OS
  server to receive and process "inbound" OTel trace
  contexts from the local and distributed application
  environments listed.  Additional product and software
  updates, *which are not included in this APAR*, may also
  be required in Db2 applications and/or the specific
  application execution environment(s) that your Db2
  applications run under, to enable OTel trace context
  propagation FROM those application execution
  environments TO Db2.
  
  In addition, the new Db2 OTel extended SMF record type 1161
  must be defined and configured on your system before use.
  Refer to the Db2 13 and the IBM z/OS Data Gatherer component
  APAR OA66345 online product documentation for details.
      **** IMPORTANT NOTE ****
  
  
  As part of this Db2 OTel trace support enhancement, new Db2
  commands, messages, and IFCID trace externals in support
  of this new functionality are also delivered.  Below is a
  brief summary of the new commands, messages, and
  IFCID trace record; please refer to the Db2 13 online
  product documentation for complete content:
  
  - New Db2 command: -START OTEL
    The Db2 -START OTEL command starts OpenTelemetry (OTel)
    processing to propagate OTel information and, optionally,
    enables the writing of extended SMF type 1161, subtype 1,
    span records.
  
    >>-START OTEL--+-------------------+--><
                   |                   |
                   |       +--YES--+   |
                   |       |       |   |
                   +-EMIT(-+--NO---+-)-+
  
  
  - New Db2 command: -STOP OTEL
    The Db2 -STOP OTEL command stops all Db2 OpenTelemetry
    (OTel) functions, including propagation of OTel
    information and writing of extended SMF type 1161,
    subtype 1, OTel span records.
  
    >>-STOP OTEL --><
  
  
  - New Db2 command: -DISPLAY OTEL
    The Db2 -DISPLAY OTEL command displays OpenTelemetry (OTel)
    status information. Depending on the status of OTEL and the
    options specified, the DISPLAY OTEL command output might
    contain the following sections.
     - Output heading for -DISPLAY OTEL
     - OTel EMIT status
     - OTel EMIT counts
     - OTel Detail section
     - OTel start time
     - OTel end time
     - End of output for -DISPLAY OTEL
  
    >>-DISPLAY OTEL--+----------+--><
                     |          |
                     +--DETAIL--+
  
  
  - New DSNW300I (DISPLAY OTEL) message
  
    DSNW300I csect-name DISPLAY OTEL display-otel-output
  
    Explanation
      This message marks the beginning of multiple lines of
      information in response to a DISPLAY OTEL command.
  
  
  - New DSNW303I (START/STOP OTEL) message
  
    DSNW303I csect-name OTEL IS ALREADY otel-status.
    THE command-name OTEL COMMAND IS IGNORED.
  
    Explanation
      OTel already had the requested status when a
      -START OTEL or -STOP OTEL command was issued.
  
  
  - New Db2 IFCID 394 - OTEL STATISTICS TRACE
    The purpose of IFCID 394 is to record a history of OTel
    running in Db2. The trace record only contains one section
    and will record the count metrics of valid and invalid
    traceparent and tracestate values received by Db2 as of
    the last issuing of either START or STOP OTEL.
  
    IFCID 394 starts by default as part of Statistics trace
    class 1. It is controlled by the STATTIME subsystem
    parameter and writes out the trace record at specified
    intervals if -START OTEL has been issued at least once
    since Db2 started. Record that shows all zeros will not
    be written out.  The IFCID 394 counters are accumulated
    for the life of Db2. IFCID 394 will be supported by SMF,
    GTF, OPX, READA, and READS.
  
  
  Complete documentation for this Db2 OpenTelemetry (OTel)
  tracing enhancement can be found in the Db2 13 online
  product documentation.  To find the changes and related
  information, search on "PH67971" or the following keywords:
  - OpenTelemetry
  - OTel
  - START OTEL
  - STOP OTEL
  - DISPLAY OTEL
  - DSNW300I
  - DSNW303I
  

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

  UO05336

Modules/Macros

• DSN3AMGP DSN3AMI2 DSN3AUCM DSN3OTLF DSN3SI30 DSN9DMPS DSN9SCN0
  DSN9SCN2 DSN9SCN5 DSN9SCN6 DSN9SCN7 DSN9SCN8 DSN9SCNA DSN9SCNB
  DSN9SCNE DSN9SCNF DSN9SCNM DSN9SCNP DSN9SCNS DSN@QWHS DSNARA00
  DSNARA70 DSNDEIB  DSNDQ9ST DSNDQW05 DSNDQWHS DSNFCDIR DSNFMDIR
  DSNFTDIR DSNFWDIR DSNLAGNX DSNLDICT DSNLDTML DSNLDUMP DSNLIINI
  DSNLIRTR DSNLJEMG DSNLJHPP DSNLJTIN DSNLQACT DSNLQCTL DSNLQINA
  DSNLTACC DSNLTEXC DSNLTINT DSNLZHC0 DSNLZHC1 DSNLZHP0 DSNLZINT
  DSNLZR00 DSNLZR02 DSNLZRDT DSNLZRPA DSNLZS00 DSNLZSAS DSNLZSBD
  DSNLZSEA DSNLZSPA DSNLZSQL DSNLZSRM DSNLZSRP DSNLZSTR DSNRUA01
  DSNRUC01 DSNVDT   DSNWAAPI DSNWACDF DSNWARDS DSNWDST1 DSNWOSMF
  DSNWVCM1 DSNWVCM3 DSNWVCST DSNWVINT DSNWVSBH DSNWVSMT DSNWVSR1
  DSNWVZCK DSNWVZIT DSNWVZPS DSNWVZSA DSNWVZSS DSNWVZXT DSNWZDG2
  DSNWZIL  DSNXEEZ  DSNXERD  DSNXERT  DSNXOD0Z
  

Fix information

• Fixed component name

  DB2 OS/390 & Z/

• Fixed component ID

  5740XYR00

Applicable component levels

• RD10 PSY UO05336

     UP25/10/22 P F510  

Fix is available

• Select the PTF appropriate for your component level. You will be required to sign in. Distribution on physical media is not available in all countries.