Optimize OpenTelemetry data

You can make application changes and follow z/TPF conventions to optimize the data that is collected on the z/TPF system for an enterprise-wide view of data in your application performance monitoring (APM) tools.

W3C trace context

The OpenTelemetry standard uses the World Wide Web Consortium (W3C) standard trace context that is embedded in the standard HTTP headers. The W3C standard trace context defines a 16-byte trace ID to uniquely identify each transaction and tie the trace results from each platform together in the APM tool. The W3C standard trace context also defines an 8-byte parent ID to establish the parent child relationship between trace results.

Make the following changes in your enterprise to use the W3C trace context:

Ensure that your edge servers generate a trace context that conforms to the W3C standard and includes the unique 16-byte trace ID for each transaction. Propagate the trace context through your enterprise as the transaction is processed on your various platforms.
If necessary, modify your systems that call or reply to the z/TPF system to send the trace ID in the HTTP W3C trace context header.

z/TPF OpenTelemetry name-value pair conventions

The tpfrtmc OpenTelemetry forwarder user exit uses the following name-value pairs if they are present when OpenTelemetry trace spans are defined.

Table 1. OpenTelemetry name-value pairs
Name	Characteristics	Description and usage
TPF_OTEL_trace_id	Horizontal name-value pair; 16 bytes of binary data	Uniquely identifies a transaction across systems in your enterprise. Set the value based on the value in the HTTP W3C trace context trace ID that is passed on the request to the z/TPF system. If this name-value pair does not exist, the tpfrtmc OpenTelemetry forwarder user exit uses 16 bytes of the IBM® portion of the IUOWID. In this scenario, you will not have an enterprise-wide view.
TPF_OTEL_span_id	Horizontal name-value pair; 8 bytes of binary data	Establishes the relationship between parent and child processes in your enterprise or ECBs on the z/TPF system. Set the value to a unique value for the transaction trace ID, such as the create time of this ECB. If this name-value pair does not exist, the tpfrtmc OpenTelemetry forwarder user exit uses a random 8-byte value.
TPF_OTEL_parent_span_id	Horizontal name-value pair; 8 bytes of binary data	Establishes the relationship between parent and child processes in your enterprise or ECBs on the z/TPF system. Set the value to one of the following values: A value based on the HTTP W3C trace context parent ID value that is passed on the request to the z/TPF system. The TPF_OTEL_span_id of the parent ECB that creates a child ECB. If this name-value pair does not exist, the tpfrtmc OpenTelemetry forwarder user exit uses 8 bytes of the IBM portion of the IUOWID.
TPF_OTEL_rc	Horizontal name-value pair; integer	Indicates the success or failure of processing a transaction. A value of 0 is interpreted as success in the OpenTelemetry trace data. Any nonzero value is interpreted as failure in the OpenTelemetry trace data. If this name-value pair does not exist, the tpfrtmc OpenTelemetry forwarder user exit does not set a default value and assumes success.
TPF_OTEL_rc_msg	Horizontal name-value pair; free-form string	Provides more information about the success or failure state of the application. Ensure that the content is concise because the string is stored in the name-value pair block area. If this name-value pair does not exist, the tpfrtmc OpenTelemetry forwarder user exit does not set a default value.
TPF_OTEL_ecb_purpose	Vertical name-value pair; free-form string	Describes the purpose of each ECB when multiple ECBs are involved in processing a transaction or message. The value is used to name the ECB spans. Ensure that the content is concise because the string is stored in the name-value pair block area. If this name-value pair does not exist, the tpfrtmc OpenTelemetry forwarder user exit does not set a default value.

Make the following changes in your z/TPF system to use the z/TPF OpenTelemetry name-value pair conventions to optimize the results in your enterprise:

Update any proprietary communications protocols as follows:
- Propagate the W3C trace context.
- Set the z/TPF OpenTelemetry name-value pairs based on the values in the W3C trace context.
- Set the z/TPF OpenTelemetry name-value pairs based on your usage, such as the return code and return code messages.
Update requests that flow over standard middleware, ideally in user exit code, as follows:
- Set the z/TPF OpenTelemetry name-value pairs based on the values in the W3C trace context.
- Set the z/TPF OpenTelemetry name-value pairs based on your usage, such as the return code and return code messages.
Use the tpf_nameValueLocalGetList and tpf_nameValueLocalSetList APIs to save and restore name-value pairs across activate-on-receipt (AOR) ECBs.
Update the name-value pair policy file to include the z/TPF OpenTelemetry name-value pairs.