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 Monitoring interceptor interfaces.

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

Tracking tokens are supported for CICS® (IPIC connections only), IMS, and Db2® (REST) in zosConnect-2.0 service providers and zosConnect-3.0 z/OS Assets.

For CICS IPIC connections, up to z/OS Connect 3.0.29.0, the tracking token is available in the user correlation data field USERCORRDATA of the task association data. From 3.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 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.

Note: zosConnect-3.0The use of tracking tokens with CICS JCICS connections is not supported.
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 Db2, (REST service provider for zosConnect-2.0) 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 that 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 Db2.

Tokens

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, 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 that it is unique.

Use the z/OS Connect SPI to implement selective tracking:

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 z/OS Connect Server. This enables z/OS Connect to warn if two monitoring products are incorrectly using the same stakeholder identifier.
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.
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 passed to CICS over IPIC connections, 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 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 the 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 A launch icon to indicate a link opens a new tab or window. https://ideas.ibm.com/products/6634806236750509081 at IBM Ideas.