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.
- 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 formatIBM_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
andOADATA1
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 Db2CURRENT 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 theQWHCCTKN_D
field of the trace record which is located using fieldsQWHCCTKN_OFF
,QWHCCTKN_LEN
, andQWHCCTKN_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.
- Create an interceptor that implements the
TrackingInterceptor
interface and return your stakeholder identifier on theTrackingInterceptor.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. - During the invocation of the
Interceptor.preInvoke
method, call theData.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
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. |
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. |
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.
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.