z/OS Connect traces in Datadog APM

Created 09 May 2022, Updated 04 Aug 2022

z/OS Connect traces are built using SMF type 123 version 2 records.

IronTap uses an internal telemetry format to create traces. When z/IRIS is configured to integrate with Datadog Trace APIs, Datadog-specific trace semantics and tags are applied, which leads one of the following results:

• Renaming of internal telemetry tags where the meaning of the tag is identical. For example host.name changes to host .

• Additional tags are added to adhere to Datadog APM framework and improve user experience.

Below is a description of Datadog-specific trace semantics and tags for z/OS Connect traces. Unless otherwise specified below, please refer to z/OS Connect Spans for a complete list of tags available for Datadog users.

Datadog trace semantics

z/OS Connect span

Datadog Tag	IronTap Telemetry tag	Notes
service	zos.connect.service.name	Refers to service endpoint of the REST API request. Example customer
operation_name	zosconnect.request	Currently the value is always: "zosconnect.request"
resource_name	http.method + " " + http.target	Example: POST /customer/add
host	host.name	Currently, values set in the host tag by z/IRIS are not supported by Datadog user interfaces.

>> Complete list z/OS Connect span tags

service:zos.connect.service.name

z/OS Connect requests are logically grouped by their service endpoints names stored in the service tag. As with other unified tags in Datadog, all traces, metrics and events are correlated across dashboards by service.

_{Click to enlarge image}

operation_name:zosconnect.request

operation_name in Datadog is a logical grouping of a unit of work and can be used to filter traces as well as selection criteria for APM Monitors. The value zosconnect.request is designated for incoming REST API requests processed by a z/OS Connect servers.

_{Click to enlarge image}

_{Click to enlarge image}

resource_name:http_method http_target

Service traces are also logically grouped by resource_name in Datadog. Similar to other HTTP requests instrumented by Datadog, z/IRIS combines the REST API method and target to create a resource_name.

Resources are listed viewed within Service Dashboards, are selection criteria in Traces and are stipulated components in the Flame Graph or Span List of the Trace View.

_{Click to enlarge image}

System-Of-Record (SOR) child span

>> Complete list of SOR span tags

service:zos.connect.service_provider.name

All SOR services represent the subsystem on mainframe that is configured to process the incoming REST API requests from z/OS Connect servers. See SOR service name mapping for more examples of possible values.

operation_name:zos.connect.service_provider.name

This field represents the logical unit of work performed by the SOR. For example wola.call or db2.call

_{Click to enlarge image}

zos.connect.sor.identifier

Describes the resource of a z/OS Connect System-Of-Record.

_{Click to enlarge image}