Tracking selected requests

You can monitor selected requests in the System of Record (SoR) by creating an interceptor that implements the TrackingInterceptor interface. This interface is only applicable to API provider requests.

Before you study this topic, you should be familiar with the information in Intercepting API provider calls and Creating a monitoring interceptor.

IBM z/OS Connect generates a system-wide unique correlator for each API and service request and sends it to the target system of record, embedded in a tracking token.

Tracking tokens are currently supported by the CICS®, IMS and REST client service providers.
  • For CICS, up to IBM z/OS Connect V3.0.29.0, the tracking token is available in the user correlation data field USERCORRDATA of the task association data.

    From V3.0.30.0, the tracking token is available in the adapter data field ODADPTRDATA1 of the task association data, and the adapter field ODADPTRID contains the IBM z/OS Connect product identifier in the format IBM_zOS_Connect_CICS_SP <product_version><product_buildlevel>.

    CICS makes this data available to applications through the INQUIRE ASSOCIATION system command. CICS also records this information in the OADID and OADATA1 fields of the DFHCICS group in the PERFORMANCE class of SMF 110 SubType 1 records.

  • For IMS, the tracking token is available in the user data fields in the OTMA header. The OMUSR_TRCKID_OFF field in the OTMA user data provides the offset to the tracking token. The tracking token is then recorded by IMS in the X'01' type log record under the MVS APPC message prefix segment.
  • For REST endpoints, the first 4 bytes of the tracking token are converted to ASCII and the remaining bytes are Base64 encoded. The result is sent in the X-Correlation-ID HTTP header on each request.
  • For Db2®, the first 4 bytes of the tracking token are converted to ASCII and the remaining bytes are Base64 encoded. The result is sent in the X-Correlation-ID HTTP header on each request.

    Db2 takes the value in the X-Correlation-ID header and assigns it to the Db2 CURRENT CLIENT_CORR_TOKEN special register for access by application processes.

    Db2 also records the value of X-Correlation-ID as the client correlation token in the accounting correlation header record of Db2 trace. The full length correlation token value is reported in the QWHCCTKN_D field of the trace record which is located using fields QWHCCTKN_OFF, QWHCCTKN_LEN, and QWHCCTKN_VAR. These trace records can be written to SMF 101 records or GTF.

For information about how to access the information in those fields, see the applicable system of record documentation. The format of tracking tokens is shown in Table 2 for CICS and IMS, and in Table 3 for REST endpoints.

Tokens

IBM z/OS Connect provides a mechanism by which monitoring products, also referred to as stakeholders, can specify selective tracking of requests in the processing system of record. For each API or service request, IBM z/OS Connect generates a unique correlator to identify the request. This correlator is embedded in a tracking token together with stakeholder tokens that are supplied by active tracking interceptors. The tracking token is sent with the request to the system of record, where the token can be programmatically inspected by the monitoring product's agent. The stakeholder tokens enable different monitoring products to supply their own indication of whether or not a request should be tracked in the system of record.

A stakeholder token contains a monitoring product's stakeholder identifier, which is a single character in the range A-Z or a-z. The format of stakeholder tokens is shown in Table 1. Monitoring products are encouraged to register their chosen identifier with IBM to ensure it is unique.

Use the z/OS Connect SPI to implement selective tracking:
  1. Create an interceptor that implements the TrackingInterceptor interface and return your stakeholder identifier on the TrackingInterceptor.getStakeholderIdentifier() method, which is called when the interceptor is activated in the IBM z/OS Connect server. This enables IBM z/OS Connect to warn if two monitoring products are incorrectly using the same stakeholder identifier.
  2. During the invocation of the Interceptor.preInvoke method, call the Data.addStakeholderToken(char stakeholderIdentifier) method to add a stakeholder token containing your stakeholder identifier to the tracking token associated with the request.
  3. Deploy your monitoring agent in the system of record to inspect the stakeholder tokens and take the appropriate monitoring action.

Format of tracking tokens

Table 1. Format of a stakeholder token
Bytes Field Type Description
0 Stakeholder identifier Character An EBCDIC character in the range A-Z or a-z, registered as the stakeholder's identifier.
1-n Reserved - Reserved for future use.
Table 2. Format of a tracking token in CICS and IMS.
Bytes Field Type Description
0-2 Product Identifier Character z/OS product identifier, 'BAQ' in EBCDIC.
3 Version Integer Version of tracking token.
4-5 Correlator length Integer Length of the correlator, in big-endian format.
6-n Correlator Byte array System-wide unique correlator.
n+1 Stakeholder token count Integer Number of stakeholder tokens.
n+2 Stakeholder token length Integer Length of stakeholder tokens. Present only if the number of stakeholder tokens is not zero. (Use this length to traverse the list of stakeholder tokens to allow for a future increase in the length of stakeholder tokens.)
n+3 Stakeholder token list Stakeholder token array List of stakeholder tokens. Present only if the number of stakeholder tokens is not zero.
Table 3. Format of a tracking token passed to REST endpoints, including Db2.
Characters Field Type Description
0-2 Product Identifier Character z/OS product identifier, 'BAQ' in ASCII.
3 Version Character Version of tracking token in ASCII.
4-n Encoded tracking information Character Base64 encoded bytes 4-(n+3) of tracking token in Table 2.

Registered stakeholder identifiers

The following products have registered stakeholder identifiers.

Table 4. Registered stakeholder identifiers
Stakeholder identifier Product
S CA SYSVIEW
Z IBM Z APM Connect

To register your product for a stakeholder identifier, contact an IBM representative or submit a request in the RFE community.