Schema version 1

Version 1 of the schema is based on SMF. A single SMF record contains an encoded form of multiple OpenTelemetry spans. A standard SMF triplet indicates the number of encoded spans that are present in the record, as shown in Table 1. The mapping macro is provided in SYS1.MACLIB(GRBOTELS).

Table 1. Extended SMF header and self-defining section layout of a z/OS® OpenTelemetry SMF record
Offsets		Name	Length	Format	Description
Extended SMF header:
0	0	OTEL_SMF_HEADER	56		See "Extended SMF record header version 1" in z/OS MVS System Management Facilities (SMF).
Self-defining section:
56	38	OTEL_OFFSET_FIRST_SPAN_SECTION	4	unsigned integer	Offset to the first span section from start of the record, which is always 64.
60	3C	*	2	-	No length field; span section lengths are dynamic.
62	3E	OTEL_NUMBER_OF_SPANS	2	unsigned integer	Number of OpenTelemetry spans in the SMF record.

OpenTelemetry span section descriptor

OpenTelemetry spans contain attributes and are pointed to by a span section descriptor, as shown in Table 2.

Table 2. z/OS OpenTelemetry span section descriptor
Offsets		Name	Length	Format	Description
0	0	OTEL_SPAN_VERSION	2	Unsigned integer	Descriptor version (set to 1).
2	2	OTEL_SPAN_LENGTH	2	Unsigned integer	Total data length.
4	4	OTEL_SPAN_EYE_CATCHER	4	EBCDIC	Constant: `SPAN`
8	8	OTEL_SPAN_START_TIME	16	STCKE	Span start time. Output representation is according to the ISO-8601 (performed via SDK).
24	18	OTEL_SPAN_END_TIME	16	STCKE	Span end time. Output representation is according to the ISO-8601 (performed via SDK).
40	28	OTEL_SPAN_TRACE_ID	32	EBCDIC	The identifier for a trace according to the OpenTelemetry Tracing API and OpenTelemetry Overview. It is worldwide unique with practically sufficient probability by being made as 16 randomly generated bytes in string representation. This is used to group all spans for a specific trace together across all processes.
72	48	OTEL_SPAN_ID	16	EBCDIC	The identifier for a span according to the Trace Context Level 2 and OpenTelemetry Overview. It is globally unique with practically sufficient probability by being made as 8 randomly generated bytes in string representation. When passed to a child span, this identifier becomes the parent span ID for the child Span.
86	56	OTEL_SPAN_PARENT_ID	16	EBCDIC	Empty for root spans. See OTEL_SPAN_ID.
102	66	OTEL_SPAN_KIND	2	Unsigned integer	Clarifies the relationship between spans that are correlated via parent/child relationships or span links. (For details, see OpenTelemetry Tracing API.) 0 Internal. The span represents an internal operation within an application. 1 Server. The span covers server-side handling of a remote request while the client awaits a response. 2 Client. The span describes a request to a remote service where the client awaits a response. 3 Producer. The span describes the initiation or scheduling of a local or remote operation. In messaging scenarios with batching, tracing individual messages requires a new PRODUCER span per message to be created. 4 Consumer. The span represents the processing of an operation initiated by a producer where the producer does not wait for the outcome.
104	68	OTEL_SPAN_NUMBER_ATTRIBUTES	2	Unsigned integer	Number of attribute sections
106	6A	OTEL_SPAN_ATTRIBUTES	*	Dynamic	Attribute sections / span section payload

OpenTelemetry attribute section descriptor

The attributes of the span are pointed to by the attribute section descriptor, as shown in Table 3.

Table 3. OpenTelemetry attribute section descriptor
Offsets		Name	Length	Format	Description
0	0	OTEL_ATTR_LENGTH	2	Unsigned integer	Total data length.
2	2	OTEL_ATTR_NAME_LENGTH	1	Unsigned integer	The attribute name length.
3	3	OTEL_ATTR_PAYLOAD_TYPE	1	Unsigned integer	The type of payload within attribute, one of the following values: Value Description 1 String 2 Boolean 3 Integer (64-bit) 4 Float (64-bit) 5 Chrono 6 Event 7 Span link 8 Array
4	4	OTEL_ATTR_NAME_AND_PAYLOAD	*	Dynamic, EBCDIC	The name of this attribute for a span. Must be rounded up to a multiple of 4 bytes and padded with zeros. Length gives length of usable data. For span links, there is no name data. For span events, this is the name of the event.
`m`		*	*	Dynamic	Attribute section payload.
The value of `m` is determined as follows: If `OTEL_ATTR_NAME_LENGTH % 4 = 0`: `m` = 4 + OTEL_ATTR_NAME_LENGTH Otherwise: `m` = 4 + OTEL_ATTR_NAME_LENGTH + (4 - OTEL_ATTR_NAME_LENGTH % 4)

Name and payload resemble key and value, as defined in the OpenTelemetry standard. The attribute section in turn contains a dynamically sized payload depending on the payload type. Thus, the attribute section can hold a variety of different types depicted in Table 4. Note that:

The descriptor version must be set to 1.
The default character set is EBCDIC (IBM1047).
Integers are stored in big endian format.

For the attribute section descriptor (Table 3), both the attribute name and the attribute payload have dynamic lengths. That means the start of the attribute payload is dynamic. It is designated by the m offset. The m offset for the attribute payload in Table 3 must be calculated based on the length prefix OTEL_ATTR_NAME_LENGTH for the attribute name. Since OTEL_ATTR_NAME_LENGTH only designates the actual usable data without padding, the padding must be considered when calculating the start of the attribute payload.

Two string attributes must be present in the span and must be exactly the first and second attributes, in the following order:

Name = "service.name": value = The name of the service emitting the span. It is constant for the lifetime of the service.
Name = "span.name": value = The name of the span.

Table 4. Types of OpenTelemetry attribute section payloads
Value	Payload type	Schema
		Offsets		Length	Format	Description
1	String	0	0	2	Unsigned integer	String length.
		2	2	2	Unsigned integer	String CCSID, IBM®-1047 EBCDIC is the default (and is currently the only supported CCSID).
		4	4	*	Based on CCSID	Payload, rounded up to a multiple of 4 bytes and padded with zeros.
2	Boolean	0	0	4	Unsigned integer	0 False 1 True
3	Integer	0	0	8	Unsigned integer	Big endian.
4	Float	0	0	8	Floating point
5	Chrono	0	0	16	STCKE	Output as ISO-8601.
6	Event	0	0	16	STCKE	Event timestamp.
		16	10	4	Unsigned	Event attribute count; can be zero.
		20	14	*	Attributes	`n` * event attribute sections.
7	Span link	0	0	4	Unsigned	Number of links.
7	Span link	4	4	*	Pairs	Trace ID 32 bytes, EBCDIC Span ID 16 bytes, EBCDIC
8	Array	0	0	1	Unsigned	Type of array elements, one of the following values: Value Description 1 String 2 Boolean 3 Integer (64-bit) 4 Float (64-bit)
		1	1	2	Unsigned	Number of entries.
		3	3	1	-	-
		4	4	*	Entries	Each array entry is formatted according to the payload type.

OpenTelemetry span status code

If the SMF encoded span that is received contains an error.type attribute, the status code of the span is set to error, as shown in Figure 1. Otherwise, the status code remains unset, as shown in Figure 2.

The image is described in the surrounding text. — Figure 1. Example span shown in an observability backend (Jaeger) when status code is set to error