Traces

• Latest Dynatrace
• Reference
• Updated on Oct 05, 2026

Distributed traces are used to capture transactions flowing through a system. Traces are made of spans, which represent the units of work within a distributed trace.

CICS Transaction Gateway spans

Semantic conventions for CTG request and response spans captured on a CTG server or CTG client. The span.kind is client for spans captured on a CTG client and is server for spans captured on a CTG server. This applies to both the request and the response.

CTG supports different request types, such as ECI, ESI, or EPI. The call type and response codes have different semantics depending on the request type. Furthermore, some fields are only populated for some request types.

CTG request fields

Request spans have attributes conforming to the following table.

ctg.request.type MUST be one of the following:

network.transport has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

CTG response fields

Response spans have attributes conforming to the following table.

ctg.request.type MUST be one of the following:

Custom service

Custom service spans represent entry points into a service or entry points to specific components within a larger application. OneAgent Code Modules can create custom service spans via automatic instrumentation rules or directly by OneAgent SDK APIs.

Custom service fields

Database Client spans

Semantic conventions for database client spans. The span.kind for database client spans is client.

A span representing a database client operation might include the operation itself and the following result processing (for example, fetch from SQL result set, MongoDB cursor operations, etc.). Besides, several similar db operations might be aggregated into a single span for efficiency.

The aggregation attributes provide information on how many db operations have been aggregated.

The db.result.* attributes represent the details of the result processing.

Database client span fields

db.system has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

network.transport has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

DL/I database attachment fields

db.dli.pcb_type MUST be one of the following:

Dynatrace RUM links

Deprecated. Replaced with frontend_link. Semantic conventions for a RUM link on Dynatrace spans. A RUM link provides backend to frontend linking information from traces to Dynatrace RUM. Unlike span links which reference other spans, the RUM link connects a span to a user event and/or user session.

Dynatrace RUM link by tracestate fields

RUM link information for a span-to-user-event and span-to-user-session correlation. This mechanism works with both OneAgent and OpenTelemetry instrumentation and is established when the Dynatrace RUM initiates a distributed trace using W3C Trace Context headers.

Dynatrace RUM link by server timing and cookie fields

RUM link information for a span-to-user-event and span-to-user-session correlation. This mechanism requires OneAgent instrumentation and is established through server-timing HTTP response header and session context from HTTP cookies.

Dynatrace RUM link by server timing only fields

RUM link information for a span-to-user-event correlation. This mechanism requires OneAgent instrumentation and is established through server-timing HTTP response header.

Dynatrace RUM link by cookie fields

RUM link information for a span-to-user-session correlation. This mechanism requires OneAgent instrumentation and is established through session context captured from HTTP cookies.

Dynatrace frontend-backend tracing links

Semantic conventions for a frontend-backend tracing link on Dynatrace spans. A frontend link connects a span to a frontend user event and/or user session, enabling tracing from frontend monitoring (such as RUM or Synthetic) to backend services. Unlike span links, which reference other spans, the frontend link bridges frontend and backend tracing.

Dynatrace frontend link by tracestate fields

Frontend-backend tracing link for span-to-user-event and span-to-user-session correlation. This mechanism works with both OneAgent and OpenTelemetry instrumentation and is established when the Dynatrace frontend (such as RUM or Synthetic) initiates a distributed trace using W3C Trace Context headers.

Dynatrace frontend link by server timing and cookie fields

Frontend-backend tracing link for span-to-user-event and span-to-user-session correlation. This mechanism requires OneAgent instrumentation and is established through server-timing HTTP response header and session context from HTTP cookies.

Dynatrace frontend link by server timing only fields

Frontend-backend tracing link for span-to-user-event correlation. This mechanism requires OneAgent instrumentation and is established through server-timing HTTP response header.

Dynatrace frontend link by cookie fields

Frontend-backend tracing link for span-to-user-session correlation. This mechanism requires OneAgent instrumentation and is established through session context captured from HTTP cookies.

Dynatrace span

The semantic conventions for the Dynatrace span and the fields the user can expect.

Hierarchical fields

The following hierarchical attributes are mandatory.

Timing fields

Attributes start_time, end_time and duration are mandatory for all spans. The attributes in the span.timing namespace are optional and represent measurements provided by the OneAgent.

Aggregation fields

OneAgent might aggregate spans having the same parent span into a single one. The aggregated span contains attributes to indicated that aggregation happened and to allow to reconstruct details. For aggregated spans the start_time holds the earliest start_time and end_time holds the latest end_time of all aggregated spans. Like for non aggreated spans duration is the difference between start_time and end_time which might differ from aggregation.duration_sum because aggregated spans were executed in parallel or there were gaps between the spans.

Sampling fields

If the span does not represent a single span, it can have attributes to support extrapolation of its values.

Currently sampling can happen two stages in the data processing. Independend where sampling happens the span has the sampling.threshold for calculation of the combined (effective) sample rate. Supportability attributes help the understand the sampling on the different stages.

If for example OneAgents samples with a probability of 25% the spans would contain the attributes sampling.threshold=54043195528445952 and supportability.atm_sampling_ratio=4.

Details about adaptive traffic management for distributed tracing can be found in the documentation.

Code fields

Event fields

Span events have their own semantics defined here.

Span events have their own semantics defined here.

Exception fields

If the span was exited by an exception or contains other exception events, the following fields are available to provide a reference to the correct exception in the list of the span.events.

Link fields

Span links have their own semantics defined here.

Frontend link fields

A frontend-backend tracing link has its own semantics.

RUM link fields

Deprecated. Replaced with span.frontend_link. A RUM link has its own semantics.

Failure detection fields

Fields that can be expected for a failure detection on a Dynatrace span. Failure detection will be applied to spans that represent requests on endpoints and incoming Istio services mesh proxies. A request is considered failed if at least one failure reason is detected and no success forcing rule matches. The combined result (failure or success) will be stored in the attribute request.is_failed. To modify failure detection behavior, modify its configuration.

dt.failure_detection.verdict MUST be one of the following:

Failure detection has its own semantics defined here.

Server fields

These attributes may be used to describe the client and server in a connection-based network interaction where there is one side (the client) that initiates the connection. This covers all TCP network interactions since TCP is connection-based and one side initiates the connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the protocol / API does not expose a clear notion of client and server). This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS.

In an ideal situation, not accounting for proxies, multiple IP addresses or host names, the server.* attributes are the same on the client and server span.

server.address

For IP-based communication, the name should be a DNS host name of the service. On client side it matches remote service name, on server side, it represents local service name as seen externally on clients.

When connecting to a URL https://example.com/foo, server.address matches "example.com" on both client and server side.

On client side, it's usually passed in form of a URL, connection string, host name, etc. Sometimes host name is only available as a string which may contain DNS name or IP address.

If network.transport is pipe, the absolute path to the file representing it is used as server.address.

For Unix domain socket, server.address attribute represents the remote endpoint address on client side and local endpoint address on server side.

Client fields

External provider fields

Attributes describing the external provider (first-party, third-party, or CDN) that an outbound call was made to.

Supportability fields

Supportability attributes help to understand the characteristics of the span.

Transaction fields

Transactions provide a unified semantic model across all service transaction types. A transaction represents a discrete unit of inbound work within a service - an endpoint request, message processing, or FaaS invocation. A single transaction root span can have multiple type attributes set simultaneously. For example, an HTTP-triggered Lambda has both transaction.is_faas_invocation = true and transaction.is_endpoint_request = true.

Service mesh fields

Service mesh spans represent requests proxied through a service mesh layer (e.g., Istio Envoy). They do not represent service transactions (transaction.is_root_span is not set).

Request fields

Request attributes allow you to enrich spans collected by OneAgents with deep-insight data which is not captured on trace data by default. They are modelled as:

The names of request and captured attributes are composed of the prefixes "captured_attribute" and "request_attribute" and the name given in the configuration by the user.

Span size fields

The calculated sizes of a span in bytes. The dt.ingest.size is calculated when the span is ingested while the dt.retain.size is calculated before the span gets stored.

Span status fields

A span contains a status consisting of a code and an optional descriptive message. The status is especially relevant if there is a known error in the application code, such as an exception in which case the span status can be set to error. The span status is only present if it is explicitly set to error or ok.

Error status reasons

The following reasons cause the span.status_code to be error:

Additional attributes

Beside the attributes listed above, arbitrary other attributes are allowed on a span.

Dynatrace span events

Semantic conventions for span events on Dynatrace spans.

Common fields

In general, a span event does not need to follow specific semantics, but typically, span events have the following common attributes.

Besides the common attributes, any arbitrary attributes are allowed for span events.

Exception fields

If exceptions happen and are captured during a span, they're available as span events. Exceptions events have the span_event.name set to exception. Besides the following exception event-specific attributes, all semantics of the common section apply.

Feature flag evaluation fields

A flag evaluation SHOULD be recorded as an event on the span during which it occurred. Feature flag events have the span_event.name set to feature_flag.evaluation.

Business event fields

If a span is related to a business event, the IDs of the business events are available as span events. The span events have the span_event.name set to bizevent.

Dynatrace span links

Semantic conventions for well known span links.

By Span and Trace Id fields

A span link by span.id and trace.id references to a target span on a different trace.

Besides the attributes listed above, arbitrary other attributes are allowed on a generic span link.

By custom link Id fields

Besides the attributes listed above, arbitrary other attributes are allowed on a generic span link. A span link by dt.tracing.custom_link.id references another span with a span link to the same dt.tracing.custom_link.id. This span link is used for technologies where full context propagation with span ID and trace ID is not possible, and only a limited amount of information can be propagated between tiers. The dt.tracing.link.direction defines the hierarchy between two spans having span links with the same dt.tracing.custom_link.id.

By foreign link fields

A span link by dt.tracing.foreign_link refers to an upstream transaction. This could be a cross-environment link or a cross-product link to a distributed trace in the legacy AppMon product. Depending on whether the link information was received in binary or text, either dt.tracing.foreign_link.bytes or dt.tracing.foreign_link.text will be set, respectively.

By response headers fields

A span link by dt.tracing.response.headers refers to a downstream transaction. This could be a cross-environment link.

ESB spans

Semantic conventions for ESB (Enterprise Service Bus) spans. An ESB span holds information about the realm in which the span is produced. This metadata includes, for example, the workflow in which the span is placed and the application or library to which the workflow belongs.

ESB spans fields

The workflow name is mandatory information and contributes the most to identifying where this span comes from. The application and library provide a high-level view of which deployment the span belongs to. It's also worth mentioning that application and library are typically seen as mutually exclusive, although this is not enforced in any way.

Failure detection result

Record containing fields that can be expected for a failure detection result. These results are part (as a record array) of a set of fields used by the failure detection feature and are referenced there via failure_detection.results. This record relates to failure detection v1 and v2.

Failure detection result aggregate fields

reason MUST be one of the following:

verdict MUST be one of the following:

Function as a Service (FaaS)

Fields that can be expected from serverless functions or Function as a Service (FaaS) on various cloud platforms. There are general attributes and attributes specific to incoming FaaS invocations (server side) and outgoing invocations (FaaS function as client calling out).

FaaS general attributes

FaaS incoming invocations

Incoming FaaS invocations as they are reported by the FaaS instance itself. For incoming FaaS spans, the span.kind is either server or consumer.

FaaS outgoing invocations

Outgoing FaaS invocations as they are reported by a client calling a FaaS instance. For outgoing FaaS spans, the span.kind is either client or producer.

Generative AI (GenAI) spans

Semantic convention for spans related with GenAI applications.

Generative AI (GenAI) span fields

gen_ai.operation.kind has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

gen_ai.operation.name has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

gen_ai.prompt_caching has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

gen_ai.provider.name has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

HTTP spans

Semantic conventions for HTTP client and server spans. They can be used for HTTP and HTTPS schemes and various HTTP versions like 1.1, 2, and SPDY.

HTTP common fields

The common fields listed in this section apply to both HTTP clients and servers in addition to the specific fields listed in the HTTP client and HTTP server sections below.

HTTP client fields

This span type represents an outbound HTTP request. For an HTTP client span, span.kind is client.

HTTP server fields

This span type represents an inbound HTTP request. For an HTTP server span, span.kind MUST be server.

Messaging spans

Messaging common fields

messaging.operation.type has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

messaging.system has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

network.transport has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

Messaging destination fields

A destination represents the component within a messaging system where messages are sent to and consumed from. A destination is usually uniquely identified by its name within the messaging system instance. Examples of a destination name would be a URL or any other identifier of a specific queue, topic, or other entity within the broker. Messaging producer and consumer spans will have the following messaging destination attributes defined.

Akka Messaging

Akka producer fields

Sender side via ActorRef.tell() or ActorSelection.tell() is represented by a span, with span.kind set to producer.

Akka consumer fields

The receiver side via ActorCell.invoke() (inproc) or Actor.receive() (tcp) is represented by a span, with span.kind set to consumer.

network.transport has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

Kafka Messaging

This convention extends the default semantic convention for messaging systems.

Kafka producer fields

Kafka consumer fields

RPC spans

Fields that describe remote procedure calls (also called "remote method invocations" / "RMI") with spans.

A remote procedure call is described by two separate spans, one on the client and one on the server side.

For outgoing requests, the SpanKind MUST be set to client and for incoming requests to server.

RPC common fields

RPC server fields

This span type represents an inbound RPC request. For an RPC server span, SpanKind is Server.

gRPC

Additional conventions for remote procedure calls via gRPC.

rpc.framework and rpc.protocol MUST be set to "grpc".

gRPC fields

gRPC

RMI

Additional conventions for remote procedure calls via RMI.

rpc.framework and rpc.protocol MUST be set to "java-rmi".

RMI fields

RMI

z/OS Connect EE spans

z/OS Connect EE (Enterprise Edition) is an IBM product that exposes applications and data in z/OS subsystems such as CICS, IMS, or MQ via a RESTful API. The z/OS Connect EE (v3.0) implementation is built on the WebSphere Application Server for the z/OS Liberty profile.

z/OS Connect client fields

zosconnect.request.type MUST be one of the following:

zosconnect.sor.type MUST be one of the following:

z/OS spans

The semantic conventions for z/OS client and server spans. You can use them for CICS and IMS schemes.

Common fields

The common attributes listed in this section apply to both CICS and IMS clients and servers, in addition to the specific attributes listed in the CICS common, CICS client, and CICS server sections below.

CICS common fields

The common attributes of a CICS client/server transaction.

CICS client fields

This span type represents an outbound CICS request. For a CICS client span, span.kind is client.

CICS server fields

This span type represents an inbound CICS request. For a CICS server span, span.kind MUST be server.