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.
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.
Request spans have attributes conforming to the following table.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | experimentalThe user ID of the user who triggered this transaction. |
|
| long | experimentalInteger representing the call type of the CTG GatewayRequest. The set of possible values varies per request type. 1 |
|
| long | experimentalLength of the COMMAREA. Only set when the request type is ECI. |
|
| long | experimentalInteger representing the extended mode of the CTG GatewayRequest. Only set when the request type is ECI. 2 |
|
| long | experimentalInteger representing the flow type of the CTG GatewayRequest. 3 |
|
| string | experimentalURL of the gateway. Only set on client-side spans. |
|
| string | experimentalName of the request object. Only set when the request type is ADMIN. | |
| string | experimentalID of the server. Not set for all request types. |
|
| string | experimentalName of the terminal resource. Only set when the request type is EPI. |
|
| string | experimentalType of the CTG GatewayRequest. |
|
| string | resource experimentalThe name of the CICS program. |
|
| string | stableOSI Transport Layer or Inter-process Communication method |
|
| string | stableLogical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. |
|
| long | stableLogical server port number. |
|
| ipAddress[] | stableA list of IP addresses that are the result of DNS resolution of |
|
| string | experimentalThe ID of this transaction. |
|
The values are defined in the IBM CTG API source code.
ctg.request.type MUST be one of the following:
| Value | Description | Display name |
|---|---|---|
| Admin request. | Admin |
| Authentication request. | Authentication request |
| Base. A base GatewayRequest without a further subtype. 1 | Base |
| External Call Interface. Enables a client application to call a CICS program synchronously or asynchronously. 2 | External Call Interface |
| External Presentation Interface. Enables a user application to install a virtual IBM 3270 terminal into a CICS server. 3 | External Presentation Interface |
| External Security Interface. Enables user applications to perform security-related tasks. 4 | External Security Interface |
| CICS Request Exit. It can be used for request retry, dynamic server selection, and rejecting non-valid requests. 5 | CICS Request Exit |
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.
| Value | Description | Display name |
|---|---|---|
| In-process communication. 1 | In-Process |
| Something else (non-IP-based). | Other |
| Named or anonymous pipe. | Pipe |
| TCP | TCP |
| UDP | UDP |
| Unix domain socket. | Unix Domain Socket |
Signals that there is only in-process communication not using a "real" network protocol in cases where network attributes would typically be expected. Usually, all other network attributes can be left out.
Response spans have attributes conforming to the following table.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | experimentalType of the CTG GatewayRequest. |
|
| long | experimentalCTG response code. The set of possible values varies per request type. 1 |
|
ctg.request.type MUST be one of the following:
| Value | Description | Display name |
|---|---|---|
| Admin request. | Admin |
| Authentication request. | Authentication request |
| Base. A base GatewayRequest without a further subtype. 1 | Base |
| External Call Interface. Enables a client application to call a CICS program synchronously or asynchronously. 2 | External Call Interface |
| External Presentation Interface. Enables a user application to install a virtual IBM 3270 terminal into a CICS server. 3 | External Presentation Interface |
| External Security Interface. Enables user applications to perform security-related tasks. 4 | External Security Interface |
| CICS Request Exit. It can be used for request retry, dynamic server selection, and rejecting non-valid requests. 5 | CICS Request Exit |
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | experimentalThe service method of a custom service. This field only exists if a custom service was created via Dynatrace OneAgent SDK. |
|
| string | experimentalThe name of a custom service. This field only exists if a custom service was created via Dynatrace OneAgent SDK. |
|
| uid | experimentalThe ID of a custom service configuration rule. This field is only present if a custom service was configured as an automatic instrumentation rule in Dynatrace. |
|
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| long | experimentalThe number of items (rows, documents,…) affected. |
|
| string | stableThe name of a collection (table, container) within the database. |
|
| double | experimentalThe cost of the request in Azure Cosmos DB request units (RU). |
|
| string[] | experimentalThe list of tables the request targets. |
|
| string | stableThe name of the database, fully qualified within the server address and port. |
|
| string | stableThe name of the operation or command executed, for example the MongoDB command name, SQL keyword, Redis command name,… 1 |
|
| record[] | experimentalThe query parameters used in db.query.text represented as a key and value map. For database systems without named keys, the map key is the string representation of the index starting with 0. Several database requests may get aggregated into a single span. Each entry in the array holds the bind parameters for one database request.Tags: |
|
| string | stableThe database query being executed. 2 |
|
| duration | experimentalThe maximum duration in nanoseconds used for fetching the result. |
|
| duration | experimentalThe minimum duration in nanoseconds used for fetching the result. |
|
| duration | experimentalThe total duration in nanoseconds used for fetching the result. |
|
| long | experimentalThe number of exceptions encountered while fetching the result. |
|
| long | experimentalThe number of operations executed on the result (for example, fetches from SQL result set, MongoDB cursor operations). |
|
| long | experimentalThe number of items requested in fetching query results. |
|
| long | experimentalThe number of round-trips triggered by fetching the result. |
|
| string | experimentalAn identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. |
|
| string | stableOSI Transport Layer or Inter-process Communication method |
|
| string | stableLogical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. |
|
| long | stableLogical server port number. |
|
| ipAddress[] | stableA list of IP addresses that are the result of DNS resolution of |
|
Depending on the data provided on ingest, this attribute may be derived by e.g., parsing db.query.text. Parsing might fail, or the result might be inaccurate.
The value may be sanitized to exclude sensitive information.
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.
| Value | Description | Display name |
|---|---|---|
| Adabas (Adaptable Database System) | Adabas |
| Amazon DocumentDB | DocumentDB |
| Amazon Aurora MySQL | Aurora MySQL |
| Amazon Aurora PostgreSQL | Aurora PostgreSQL |
| InterSystems Caché | InterSystems Caché |
| Apache Cassandra | Cassandra |
| ClickHouse | ClickHouse |
| Cloudscape | Cloudscape |
| CockroachDB | CockroachDB |
| ColdFusion IMQ | ColdFusion IMQ |
| Microsoft Azure Cosmos DB | Cosmos DB |
| Couchbase | Couchbase |
| CouchDB | CouchDB |
| Databricks Data Platform | Databricks Data Platform |
| IBM Db2 | IBM Db2 |
| Apache Derby | Derby |
| IBM DL/I | IBM DL/I |
| Amazon DynamoDB | DynamoDB |
| EnterpriseDB | EnterpriseDB |
| Elasticsearch | Elasticsearch |
| FileMaker | FileMaker |
| Firebird | Firebird |
| FirstSQL | FirstSQL |
| Apache Geode | Geode |
| H2 | H2 |
| SAP HANA | SAP HANA |
| Apache HBase | HBase |
| Apache Hive | Hive |
| HyperSQL DataBase | HSQLDB |
| Informix | Informix |
| Ingres | Ingres |
| InstantDB | InstantDB |
| InterBase | InterBase |
| Amazon Keyspaces for Apache Cassandra | Keyspaces |
| MariaDB | MariaDB |
| SAP MaxDB | SAP MaxDB |
| Memcached | Memcached |
| MongoDB | MongoDB |
| Microsoft SQL Server | SQL Server |
| Microsoft SQL Server Compact | SQL Server Compact |
| MySQL | MySQL |
| Neo4j | Neo4j |
| Amazon Neptune | Neptune |
| Netezza | Netezza |
| OpenSearch | OpenSearch |
| Oracle Database | Oracle |
| Some other SQL database. Fallback only. See notes. | Other SQL |
| Pervasive PSQL | Pervasive PSQL |
| Apache Phoenix | Apache Phoenix |
| PointBase | PointBase |
| PostgreSQL | PostgreSQL |
| Progress Database | Progress |
| Redis | Redis |
| Amazon Redshift | Redshift |
| Snowflake Data Platform | Snowflake Data Platform |
| Cloud Spanner | Cloud Spanner |
| SQLite | SQLite |
| Sybase | Sybase |
| Teradata | Teradata |
| Valkey | Valkey |
| Vertica | Vertica |
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.
| Value | Description | Display name |
|---|---|---|
| In-process communication. 1 | In-Process |
| Something else (non-IP-based). | Other |
| Named or anonymous pipe. | Pipe |
| TCP | TCP |
| UDP | UDP |
| Unix domain socket. | Unix Domain Socket |
Signals that there is only in-process communication not using a "real" network protocol in cases where network attributes would typically be expected. Usually, all other network attributes can be left out.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | experimentalThe name of the program communication block associated with this DL/I method. |
|
| string | experimentalThe name of the last segment that was matched or returned. |
|
| string | experimentalThe hierarchical level of the segment that was matched or returned. |
|
| string | experimentalThe PCB processing options. |
|
| string | experimentalThe DL/I database or logical terminal name associated with this DL/I method. |
|
| string | experimentalThe DL/I status code. |
|
| string | experimentalThe PCB type. |
|
db.dli.pcb_type MUST be one of the following:
| Value | Description | Display name |
|---|---|---|
| Data communications. | Data communications |
| DL/I db. | DL/I |
| Fast Path. | Fast Path |
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.
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | resource stableA persistent pseudonymous identifier representing the same device (browser user agent or mobile app installation) across multiple user sessions. Used to analyze returning users and long-term journeys. Formerly known as "Visitor ID" or "internal user ID." For information on the real user identity, see |
|
| string | stableA unique identifier for a user session. Use this field to join user events with user sessions in DQL queries. |
|
| uid | stableThe |
|
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | resource stableA persistent pseudonymous identifier representing the same device (browser user agent or mobile app installation) across multiple user sessions. Used to analyze returning users and long-term journeys. Formerly known as "Visitor ID" or "internal user ID." For information on the real user identity, see |
|
| boolean | experimentalIndicates that a user event likely exists that can be correlated to this trace. Use the |
|
| string | stableA unique identifier for a user session. Use this field to join user events with user sessions in DQL queries. |
|
RUM link information for a span-to-user-event correlation.
This mechanism requires OneAgent instrumentation and is established through server-timing HTTP response header.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| boolean | experimentalIndicates that a user event likely exists that can be correlated to this trace. Use the |
|
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | resource stableA persistent pseudonymous identifier representing the same device (browser user agent or mobile app installation) across multiple user sessions. Used to analyze returning users and long-term journeys. Formerly known as "Visitor ID" or "internal user ID." For information on the real user identity, see |
|
| string | stableA unique identifier for a user session. Use this field to join user events with user sessions in DQL queries. |
|
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.
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | resource stableA persistent pseudonymous identifier representing the same device (browser user agent or mobile app installation) across multiple user sessions. Used to analyze returning users and long-term journeys. Formerly known as "Visitor ID" or "internal user ID." For information on the real user identity, see |
|
| string | stableA unique identifier for a user session. Use this field to join user events with user sessions in DQL queries. |
|
| uid | stableThe |
|
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | resource stableA persistent pseudonymous identifier representing the same device (browser user agent or mobile app installation) across multiple user sessions. Used to analyze returning users and long-term journeys. Formerly known as "Visitor ID" or "internal user ID." For information on the real user identity, see |
|
| boolean | experimentalIndicates that a user event likely exists that can be correlated to this trace. Use the |
|
| string | stableA unique identifier for a user session. Use this field to join user events with user sessions in DQL queries. |
|
Frontend-backend tracing link for span-to-user-event correlation.
This mechanism requires OneAgent instrumentation and is established through server-timing HTTP response header.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| boolean | experimentalIndicates that a user event likely exists that can be correlated to this trace. Use the |
|
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | resource stableA persistent pseudonymous identifier representing the same device (browser user agent or mobile app installation) across multiple user sessions. Used to analyze returning users and long-term journeys. Formerly known as "Visitor ID" or "internal user ID." For information on the real user identity, see |
|
| string | stableA unique identifier for a user session. Use this field to join user events with user sessions in DQL queries. |
|
The semantic conventions for the Dynatrace span and the fields the user can expect.
The following hierarchical attributes are mandatory.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| uid | experimentalThe alternative |
|
| uid | stableA unique identifier for a span within a trace. The |
|
| boolean | experimentalIf set to | |
| string | stableDistinguishes between spans generated in a particular context. |
|
| uid | stableThe |
|
| uid | stableA unique identifier for a trace. The |
|
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| duration | stableThe difference between |
|
| timestamp | stableEnd time of a data point. Value is a UNIX Epoch time in nanoseconds and greater than or equal to the |
|
| duration | stableThe overall CPU time spent executing the span, including the CPU times of child spans that are running on the same thread on the same call stack. | |
| duration | stableThe CPU time spent exclusively on executing this span, not including the CPU times of any children. | |
| timestamp | stableStart time of a data point. Value is a UNIX Epoch time in nanoseconds and less than or equal to the |
|
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| long | stableThe number of spans aggregated into this span. Because this span represents multiple spans, the value is >1. |
|
| duration | stableThe duration in nanoseconds for the longest aggregated span. |
|
| duration | stableThe duration in nanoseconds for the shortest aggregated span. |
|
| duration[] | stableArray of reservoir sampled span durations of the aggregated spans. The duration samples can be used to estimate a more accurate duration distribution of aggregated spans rather than the average value. |
|
| duration | stableThe duration sum in nanoseconds for all aggregated spans. |
|
| long | stableThe number of aggregated spans that included an exception. |
|
| boolean | stable |
If the span does not represent a single span, it can have attributes to support extrapolation of its values.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| long | experimentalThe sampling probability is encoded as |
|
| long | experimentalThe denominator of the sampling ratio of the Dynatrace cluster, the attribute is only set if Adaptive Load Redution (ALR) is active on the Dynatrace cluster. A numerator is not specified, as it's always 1. If, for example, the Dynatrace cluster samples with a probability of 1/8 (12,5%), the value of |
|
| long | experimentalThe denominator of the sampling ratio of an Adaptive Traffic Management (ATM) aware sampler. The attribute is always present if an ATM-aware sampler is active (this applies, for example, to Dynatrace OneAgent). A numerator is not specified, as it is always 1. If, for example, Dynatrace OneAgent samples with a probability of 1/16 (6,25%), the value of |
|
| string[] | experimentalExplains why this trace was captured, multiple reasons can apply simultaneously. Note: The sampling approach ('atm' or 'fixed') is always placed at the first position in the array. These two values are mutually exclusive, though 'fixed' may appear with other capture triggers. Values: 'atm' (Dynatrace's intelligent sampling automatically adjusted trace capture based on traffic volume and system load), 'fixed' (trace captured due to configured percentage rules - either global settings or specific endpoint rules), 'custom' (trace captured because of custom correlation headers propagated between services or systems), 'mainframe' (trace originated from or includes IBM mainframe/z/OS components), 'serverless' (trace captured from serverless functions like AWS Lambda, Azure Functions, or similar platforms), 'rum' (trace initiated by user interactions in web browsers or mobile apps monitored by Dynatrace RUM agents). |
|
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.
supportability.atm_sampling_ratio is added to all effected spans.supportability.alr_sampling_ratio is added to all effected spans.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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | experimentalThe method or function name, or equivalent (usually the rightmost part of the code unit's name). Represents the name of the function that is represented by this span. |
|
| string | experimentalThe namespace within which |
|
| string | experimentalThe source code file name that identifies the code unit as uniquely as possible. |
|
| long | experimentalThe line number within the source code file. |
|
| string | experimentalLike |
|
| string | experimentalLike |
|
| string | experimentalLike |
|
| string | experimentalThe call stack of the |
|
Span events have their own semantics defined here.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| record[] | stableA collection of events. An event is an optional time-stamped annotation of the span and consists of a name and key-value pairs. | |
| long | experimentalThe number of span events that were discarded on the source. |
|
Span events have their own semantics defined here.
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| uid | stableThe | |
| boolean | stableSet to |
Span links have their own semantics defined here.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| record[] | stableA collection of links. A link is a reference from this span to a whole trace or a span in the same or different trace. | |
| long | experimentalThe number of span links that were discarded on the source. |
|
A frontend-backend tracing link has its own semantics.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| record | experimentalA frontend-backend tracing link that connects a span to a frontend user event and/or user session. Unlike span links, which reference other spans, this links tracing data to frontend monitoring (such as RUM or Synthetic). |
Deprecated. Replaced with span.frontend_link. A RUM link has its own semantics.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| record | **deprecatedReplaced with |
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| uid | experimentalThe |
|
| uid | experimentalThe |
|
| uid | experimentalThe |
|
| uid | experimentalThe |
|
| record[] | experimentalA collection of individual failure detection reasons and verdicts for each applied matching rule. If no entries exist, no rules matched, and the attribute does not exist. | |
| uid | experimentalThe |
|
| string | experimentalThe final failure detection verdict based on the results in |
|
dt.failure_detection.verdict MUST be one of the following:
| Value | Description | Display name |
|---|---|---|
| There is at least one result with verdict | Failure |
| There is at least one result with verdict | Success |
Failure detection has its own semantics defined here.
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | stableLogical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. |
|
| long | stableLogical server port number. |
|
| ipAddress[] | stableA list of IP addresses that are the result of DNS resolution of |
|
server.addressFor 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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | experimentalClient address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. |
|
| string | experimentalThe name of the client application used to perform the request. |
|
| ipAddress | experimentalThe IP address of the client that makes the request. This can be IPv4 or IPv6.Tags: |
|
| boolean | experimentalIndicates whether IP is a public IP. |
|
| string | experimentalThe name of the Internet Service Provider (ISP) associated with the client's IP address. |
|
| long | stableClient port number. |
|
Supportability attributes help to understand the characteristics of the span.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| long | experimentalThe number of attributes that were discarded on the source. Attributes can be discarded because their keys are too long or because there are too many attributes. |
|
| string[] | experimentalA string array of attribute keys that were not stored as they were not allow-listed or were removed during the pipeline steps. |
|
| uid | experimentalThe preserved trace ID when OneAgent and other tracing systems monitor the same process and the trace ID from the other tracing system was replaced by the OneAgent trace ID. The |
|
| string | experimentalThe trace state in the w3c-trace-context format. |
|
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| uid | experimentalThe ID of the endpoint detection rule that was applied to that span. |
|
| string | stableThe endpoint name is derived from endpoint detection rules and uniquely identifies one endpoint of a particular service. Endpoint names are usually technology-specific and should be defined by attributes with low cardinality, like |
|
| boolean | **deprecatedReplaced by | |
| boolean | **deprecatedReplaced by | |
| boolean | experimentalIndicates that this transaction is an endpoint request. Set by the endpoint detection ruleset. | |
| boolean | experimentalIndicates that this transaction is a FaaS invocation. Set when | |
| boolean | experimentalIndicates that the transaction is considered failed according to the failure detection rules. Only present on the transaction root span. | |
| boolean | experimentalIndicates that this transaction is a message processing transaction. Set when | |
| boolean | experimentalMarks the root span of a transaction. A span becomes a transaction root if at least one transaction type attribute is set. |
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).
| Attribute | Type | Description | Examples |
|---|---|---|---|
| boolean | experimentalIndicates that the service mesh request is considered failed according to the failure detection rules. Only present on the service mesh root span. | |
| boolean | experimentalMarks the root span of a service mesh request. Set by the service mesh detection ruleset. |
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| array | stableContains the span scoped raw values that were captured under the name |
|
| array | stableContains the request scoped reconciled values of the attribute named |
|
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| long | stableThe size of the ingested data point in bytes. |
|
| long | stableThe size of the retained data point in bytes. |
|
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | stableDefines the status of a span, predominantly used to indicate a processing error. This field is absent if the reported span status is |
|
| string | experimentalAn optional text that can provide a descriptive error message in case the |
|
The following reasons cause the span.status_code to be error:
span.is_exit_by_exception is set to true.http.response.status_code values in the 5xx range.span.kind is client: for http.response.status_code values in the 4xx range.span.kind is client: for all rpc.grpc.status_code values except OK (0).span.kind is server: for rpc.grpc.status_code values UNKNOWN (2), DEADLINE_EXCEEDED (4), UNIMPLEMENTED (12), INTERNAL (13), UNAVAILABLE (14), DATA_LOSS (15).This document describes how the Dynatrace span name is defined for specific technologies.
To be considered for the name, all attributes in the below definitions must be available and not empty. If individual fields are not available, multiple items in a technology-specific list show alternatives for the name.
If none of these technology-specific attributes are available, the span name defaults to code.namespace.code.function, or only code.function if code.namespace is not available. For serverless functions (Function as a Service (FaaS)), it defaults to faas.name for the function entry span (holding faas.trigger span attribute).
For the OneAgent OpenTelemetry and OpenTracing integration, the already defined span operation name (OpenTracing) is used as the Dynatrace span.name.
The fallback name is span.kind, such as client or server.
Beside the attributes listed above, arbitrary other attributes are allowed on a span.
Semantic conventions for span events on Dynatrace spans.
In general, a span event does not need to follow specific semantics, but typically, span events have the following common attributes.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | stableSome span events have a defined semantics based on the name of the span event. |
|
| long | experimentalThe number of attributes that were discarded on the source. Attributes can be discarded because their keys are too long or because there are too many attributes. |
|
| string[] | experimentalA string array of attribute keys that were not stored as they were not allow-listed or were removed during the pipeline steps. |
|
| timestamp | stableThe time (UNIX Epoch time in nanoseconds) when the event originated, typically when the source created it. If no original timestamp is available, it will be populated at ingest time and required for all events. In the case of a correlated event (for example, ITIL events), this time could be different from the event.start time, as this time represents the actual timestamp when the "update" for the event was created. |
|
Besides the common attributes, any arbitrary attributes are allowed for span events.
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| uid | stableThe | |
| boolean | stable | |
| uid | stableThe identifier of an exception. It should be unique within a list of exceptions of a span. The identifier is used to reference the exception. | |
| boolean | stableIs set to | |
| string | stableA message that describes the exception. |
|
| string | experimentalThe stack trace of the exception. The format depends on the technology and source. While OneAgent formats stack traces to unify them across technologies, stack traces from an OpenTelemetry source are in the format they were sent to Dynatrace. |
|
| string | stableThe type of the exception, for example, its fully-qualified class name. |
|
| string | stableIs set to |
|
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | experimentalThe unique identifier for the flag evaluation context. For example, the targeting key. |
|
| string | experimentalThe unique identifier of the feature flag. |
|
| string | experimentalThe name of the service provider that performs the flag evaluation. |
|
| string | experimentalThe reason code, which shows how a feature flag value was determined. |
|
| string | experimentalA semantic identifier for an evaluated flag value. 1 |
|
| string | experimentalThe identifier of the flag set to that the feature flag belongs. |
|
| string | experimentalThe version of the ruleset used during the evaluation. This can be any stable value that uniquely identifies the ruleset. |
|
| string | stableIs set to |
|
A semantic identifier, commonly referred to as a variant, provides a means
for referring to a value without including the value itself. This can
provide additional context for understanding the meaning behind a value.
For example, the variant red maybe be used for the value #c05543.
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | stableUnique identifier string of an event; is stable across multiple refreshes and updates. |
|
| string | stableIs set to |
|
Semantic conventions for well known span links.
A span link by span.id and trace.id references to a target span on a different trace.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| uid | stableA unique identifier for a span within a trace. The |
|
| long | experimentalThe number of attributes that were discarded on the source. Attributes can be discarded because their keys are too long or because there are too many attributes. |
|
| string[] | experimentalA string array of attribute keys that were not stored as they were not allow-listed or were removed during the pipeline steps. |
|
| uid | experimentalThe preserved trace ID when OneAgent and other tracing systems monitor the same process and the trace ID from the other tracing system was replaced by the OneAgent trace ID. The |
|
| uid | stableA unique identifier for a trace. The |
|
| string | experimentalThe trace state in the w3c-trace-context format. |
|
Besides the attributes listed above, arbitrary other attributes are allowed on a generic span link.
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| uid | experimentalThe custom link ID to identify spans calling each other. The ID is derived from the custom link bytes. |
|
| binary | experimentalThe original binary data of the custom link. |
|
| binary | experimentalThe transformed binary data of the custom link. Only available if a mapping was applied. |
|
| string | experimentalThe type of the custom link defines if a mapping of the |
|
| string | experimentalThe direction of the span link to define the correct order between spans. |
|
| boolean | experimental | |
| timestamp | stableThe time (UNIX Epoch time in nanoseconds) when the span was propagated. Only available on span links with |
|
A Dynatrace link provides additional details regarding the parent and child timing on top of span.parent_id.
This data is optional and not provided by all span data sources.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | experimentalThe direction of the span link to define the correct order between spans. |
|
| uid | experimentalUnique identifier for a Dynatrace link. | |
| boolean | experimental | |
| timestamp | stableThe time (UNIX Epoch time in nanoseconds) when the span was propagated. Only available on span links with |
|
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| binary | experimentalAn incoming foreign link (cross-environment or cross-product). |
|
| string | experimentalAn incoming foreign link (cross-environment or cross-product). |
|
A span link by dt.tracing.response.headers refers to a downstream transaction. This could be a cross-environment link.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| record | experimentalA collection of key-value pairs containing received response headers related to tracing from an outgoing call. There may be multiple values for each header. Used for cross-environment linking. |
|
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.
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | resource experimentalThe name of the application that owns the current workflow. |
|
| string | resource experimentalThe name of the library that owns the current workflow. |
|
| string | resource experimentalThe name of vendor of the ESB technology of the current workflow. |
|
| boolean | experimentalDefines whether the provided workflow is a subprocess or not. |
|
| string | resource experimentalThe label of the current workflow. |
|
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | experimentalName of the custom rule that caused this result. Uniquely identifies the rule within a failure detection v2 rule set. Related to the |
|
| uid | experimentalIDs of the exceptions that caused this rule result (more on exceptions). |
|
| string | experimentalAll possible failure detection reasons that caused a verdict. |
|
| string | experimentalName of the request attribute that caused this result. Related to a custom error rule in a failure detection v1 configuration and the |
|
| string | experimentalAll possible failure detection verdicts. |
|
reason MUST be one of the following:
| Value | Description |
|---|---|
| Verdict is caused by a custom error rule (request attribute). Applicable in failure detection v1. This reason always comes together with the |
| Verdict is caused by a custom rule. Applicable in failure detection v2. This reason always comes together with the |
| Verdict is caused by an exception. Applicable in failure detection v1 and v2. |
| Verdict is caused by the GRPC response code. Applicable in failure detection v2. |
| Verdict is caused by the HTTP response code. Applicable in failure detection v1 and v2. |
| Verdict is caused by the span status attribute. Applicable in failure detection v1 and v2. |
verdict MUST be one of the following:
| Value | Description |
|---|---|
| Indicates that the rule failed. |
| Indicates that the rule was successful. |
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).
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | resource stableThe 12-digit number, such as 123456789012, that uniquely identifies an AWS account.Tags: |
|
| string | resource stableAmazon Resource Name (ARN). |
|
| string | resource stableA specific geographical AWS Cloud location.Tags: |
|
| string | resource experimentalThe fully qualified name of the class executing an Azure function. |
|
| string | resource stableA specific geographical location of Azure cloud resource.Tags: |
|
| string | resource experimentalA unique, immutable identifier assigned to each Azure cloud resource. |
|
| string | resource experimentalGlobally unique deployment information about an Azure function. |
|
| string | resource stableAn Azure subscription is a logical container used to provision resources in Azure.Tags: |
|
| string | resource deprecatedDeprecated in favor of cloud specific fields, such as aws.account.id, azure.subscription, gcp.project.id, etc. |
|
| string | resource deprecatedDeprecated, no replacement available. 1 |
|
| string | resource stableName of the cloud provider. |
|
| string | resource deprecatedDeprecated in favor of cloud specific fields, such as aws.region, azure.location, gcp.region, etc. |
|
| string | resource deprecatedDeprecated in favor of cloud specific fields, such as aws.arn, azure.resource.id, gcp.resource.name, etc. |
|
| long | resource experimentalThe amount of memory available to the serverless function in Bytes. | |
| string | resource experimentalThe name of the single function that this runtime instance executes. 2 |
|
| string | resource experimentalThe immutable version of the function being executed. 3 |
|
| string | resource stableIdentifier of the GCP project associated with this resource.Tags: |
|
| string | resource stableA region is a specific geographical location where you can host your resources.Tags: |
|
| string | resource stableThe globally unique resource name in Google Cloud Platform convention. |
|
The prefix of the service matches the one specified in cloud.provider.
This is the name of the function as configured/deployed on the FaaS platform and is usually different from the name of the callback
function (which may be stored in the code.namespace/code.function span attributes).
Value of the field depends on a cloud provider. This field is not set for Azure.
Incoming FaaS invocations as they are reported by the FaaS instance itself. For incoming FaaS spans, the span.kind is either server or consumer.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | experimentalThe AWS request ID (e.g., value of |
|
| string | experimentalContains the AWS X-Ray trace id (e.g., value of the |
|
| boolean | experimentalA boolean that is true if the serverless function is executed for the first time (aka cold-start). | |
| string | experimentalThe table/collection name on which the operation |
|
| string | experimentalThe identifier for the specific item that changed after executing the operation above. 2 |
|
| string | experimentalRelevant only for "datasource" trigger. The operation type which triggered the function invocation. |
|
| string | experimentalThe UTC ISO-8601 timestamp of the operation above. 3 |
|
| string | stableFaaS event attribute, the |
|
| string | experimentalThe API action that triggered the FaaS event. 4 |
|
| string | experimentalThe cloud service that originated the event. |
|
| string | experimentalThe schedule expression that configures the timer trigger for the function invocation (for |
|
| timestamp | experimentalThe timestamp when the timer expired and triggered the function execution (for |
|
| string | experimentalType of the trigger which caused this function invocation. |
|
Relevant only for faas.trigger=datasource trigger
Relevant only for faas.trigger=datasource trigger
Relevant only for faas.trigger=datasource trigger
The value of this attribute is specific to the service that generated the event.
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | experimentalThe AWS request ID (e.g., value of |
|
| string | experimentalContains the AWS X-Ray trace id (e.g., value of the |
|
| string | experimentalThe name of the invoked function. |
|
| string | experimentalThe cloud provider of the invoked function. Will be equal to the invoked function's |
|
| string | experimentalThe cloud region of the invoked function. 1 |
|
Will be equal to the invoked function's cloud.region resource attribute.
Semantic convention for spans related with GenAI applications.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | experimentalHuman-readable name of the GenAI agent provided by the application. |
|
| long | experimentalThe number of dimensions the resulting output embeddings should have. |
|
| string | experimentalIdentifier of the guardrail that has been activated for the request. |
|
| record[] | experimentalContent categories that triggered the guardrails on prompts. |
|
| long | experimentalProcessing time of prompt by guardrail in ms. |
|
| string[] | experimentalName of the patterns for sensitive information in prompt that triggered the Guardrail. |
|
| string[] | experimentalPersonal Identifiable Information categories in prompt that triggered the Guardrail. |
|
| string[] | experimentalTopics in prompt that triggered the Guardrail. |
|
| string[] | experimentalWord lists that triggered the guardrail for prompt. |
|
| string[] | experimentalWords in prompt that triggered the Guardrail. |
|
| record[] | experimentalContent categories that triggered the guardrails on response. |
|
| record[] | experimentalContextual check types that triggered the guardrail on the response, along with the score achieved by each triggered grounding check. |
|
| long | experimentalProcessing time of response by guardrail in ms. |
|
| string[] | experimentalName of the patterns for sensitive information in response that triggered the Guardrail. |
|
| string[] | experimentalPersonal Identifiable Information categories in response that triggered the Guardrail. |
|
| string[] | experimentalTopics in response that triggered the Guardrail. |
|
| string[] | experimentalWord lists that triggered the guardrail for response. |
|
| string[] | experimentalWords in response that triggered the Guardrail. |
|
| string | experimentalVersion of the guardrail that has been activated. |
|
| record[] | experimentalList of all user prompts passed to the LLM. This includes "tool" prompts and may include "system" prompts if the instrumented library includes them in the message list. |
|
| string | experimentalAI framework operation being performed. |
|
| string | experimentalName of operation being performed. |
|
| record[] | experimentalList of all LLM responses. |
|
| string | experimentalIndicates how prompt cache has been used when handling the request. |
|
| string | experimentalName of GenAI product being used. |
|
| string[] | experimentalThe encoding formats requested in an embeddings operation, if specified. |
|
| double | experimentalFrequency penalty setting for GenAI request. |
|
| long | experimentalMaximum number of tokens that the model can generate for a request. |
|
| string | experimentalModel chosen to handle the request. |
|
| double | experimentalPresence penalty setting for GenAI request. |
|
| string[] | experimentalList of sequences that will stop the model from generating further tokens. |
|
| double | experimentalTemperature setting for GenAI request. |
|
| long | experimentalTemperature setting for GenAI request. |
|
| double | experimentalTemperature setting for GenAI request. |
|
| string[] | experimentalList of reasons why the model stopped generating tokens, corresponding to each generation received. |
|
| string | experimentalUnique identifier of an LLM response. |
|
| string | experimentalModel that handled the request. |
|
| string | experimentalIdentifier of system used to generate LLM response. |
|
| record[] | experimentalList of all system prompts passed to the LLM, which are not part of input messages list. |
|
| long | experimentalNumber of tokens sent to the model in the request. |
|
| long | experimentalNumber of tokens generated by the model while handling the request. |
|
| long | experimentalNumber of tokens that has been read from cache. |
|
| long | experimentalNumber of tokens used to generate cache checkpoint. |
|
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.
| Value | Description | Display name |
|---|---|---|
| Operation invoking an autonomous component that can make decisions or perform actions. | Agent |
| Operation collecting documents for a RAG pipeline. | Retrieval |
| A specific operation or step within a workflow. | Task |
| Operation invoking a utility or function used within the application. | Tool call |
| A high-level process or chain of operations. | Workflow |
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.
| Value | Description | Display name |
|---|---|---|
| Operation of engaging in a conversational exchange with LLM. | Chat |
| Operation of creating embeddings from user input. | Embeddings |
| Operation of completing text based on user input by LLM. | Text Completion |
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.
| Value | Description | Display name |
|---|---|---|
| Cache hit. Reading from cache. | Read |
| Cache miss. Creating cache checkpoint. | Write |
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.
| Value | Description | Display name |
|---|---|---|
| Amazon Bedrock | Amazon Bedrock |
| OpenAI | OpenAI |
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.
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| long | stableThe size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the Content-Length header. For requests using transport encoding, this should be the compressed size. |
|
| string | stableHTTP request headers, |
|
| string | stableHTTP request method. |
|
| long | stableThe size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the Content-Length header. For requests using transport encoding, this should be the compressed size. |
|
| string | stableHTTP response headers, |
|
| long | stableHTTP response status code. |
|
| string | stableOSI Application Layer or non-OSI equivalent. |
|
| string | experimentalVersion of the application layer protocol used. |
|
This span type represents an outbound HTTP request.
For an HTTP client span, span.kind is client.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | stableHost identifier of the "URI origin" HTTP request is sent to. |
|
| long | stablePort identifier of the "URI origin" HTTP request is sent to. |
|
| ipAddress[] | stableA list of IP addresses that are the result of DNS resolution of |
|
| string | stableThe URI fragment component. |
|
| string | stableAbsolute URL describing a network resource according to RFC3986.Tags: |
|
| string | stableThe URI path component. |
|
| string | stableThe URI query component.Tags: |
|
| string | stableThe URI scheme component identifying the used protocol. |
|
This span type represents an inbound HTTP request.
For an HTTP server span, span.kind MUST be server.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| ipAddress | experimentalIP address of the original client (IPv4 or IPv6) making the request. This request might have passed several proxies or load balancers. The client IP is the result of resolving the socket connection, X-Forward-For, and other headers.Tags: |
|
| string | stableThe matched route (path template in the format used by the respective server framework). |
|
| string | stableName of the local HTTP server that received the request. |
|
| long | stableLogical server port number. |
|
| string | stableThe URI path component. |
|
| string | stableThe URI query component.Tags: |
|
| string | stableThe URI scheme component identifying the used protocol. |
|
| Attribute | Type | Description | Examples |
|---|---|---|---|
| long | experimentalThe number of messages in the batch for which publishing failed. |
|
| string[] | experimentalThe vendor-provided error codes explaining why an operation on the message broker failed. To limit attribute size, not all error codes might be included. |
|
| long | stableThe number of messages sent, received, or processed in the scope of the batching operation. |
|
| string | stableA unique identifier for the client that consumes or produces a message. |
|
| boolean | **deprecatedReplaced by | |
| long | stableThe (uncompressed) size of the message payload in bytes. |
|
| string | stableThe conversation ID identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". |
|
| record | stableThe message headers, |
|
| string | stableA value used by the messaging system as an identifier for the message, represented as a string. |
|
| string | stableA string identifying the kind of messaging operation. |
|
| string | stableAn identifier for the messaging system. See below for a list of well-known identifiers. |
|
| string | stableOSI Application Layer or non-OSI equivalent. |
|
| string | stableOSI Transport Layer or Inter-process Communication method 1 |
|
| string | stableLogical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. 2 |
|
| long | stableLogical server port number. |
|
| ipAddress[] | stableA list of IP addresses that are the result of DNS resolution of |
|
Only necessary when the server.* attributes don't apply.
This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from.
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.
| Value | Description | Display name |
|---|---|---|
| A message is received from a destination by a message consumer/server, but left there ( | Peek |
| A message previously received from a destination is processed by a message consumer ( | Process |
| A message is sent to a destination by a message producer ( | Publish |
| A message is received from a destination by a message consumer ( | Receive |
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.
| Value | Description | Display name |
|---|---|---|
| ActiveMQ | ActiveMQ |
| ActiveMQ Artemis | ActiveMQ Artemis |
| Amazon EventBridge | AWS EventBridge |
| Amazon Simple Notification Service (SNS) | AWS SNS |
| Amazon Simple Queue Service (SQS) | AWS SQS |
| Azure Event Grid | Azure Event Grid |
| Azure Event Hubs | Azure Event Hub |
| Azure Service Bus | Azure Service Bus |
| Google Cloud Pub/Sub | GCP Pub/Sub |
| HornetQ | HornetQ |
| Java Message Service | JMS |
| Apache Kafka | Kafka |
| IBM MQ | IBM MQ |
| MSMQ | MSMQ |
| RabbitMQ | RabbitMQ |
| Apache RocketMQ | RocketMQ |
| Software AG, webMethods Integration Server | webMethods IS |
| Tibco EMS | TIBCO EMS |
| Oracle WebLogic | WebLogic |
| IBM WebSphere Application Server | WebSphere |
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.
| Value | Description | Display name |
|---|---|---|
| In-process communication. 1 | In-Process |
| Something else (non-IP-based). | Other |
| Named or anonymous pipe. | Pipe |
| TCP | TCP |
| UDP | UDP |
| Unix domain socket. | Unix Domain Socket |
Signals that there is only in-process communication not using a "real" network protocol in cases where network attributes would typically be expected. Usually, all other network attributes can be left out.
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | stableThe destination's manager name 1 |
|
| string | stableThe message destination name 2 |
|
| boolean | stableA boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. |
Manager name uniquely identifies the broker.
Destination name uniquely identifies a specific queue, topic or other entity within the broker.
Sender side via ActorRef.tell() or ActorSelection.tell() is represented by a span, with span.kind set to producer.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | experimentalPath to actor inside actor system. |
|
| string | experimentalName of the actor system. |
|
| string | experimentalFully qualified type name of the message. |
|
| long | stableThe (uncompressed) size of the message payload in bytes. |
|
| string | stableLogical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. |
|
| long | stableLogical server port number. |
|
| ipAddress[] | stableA list of IP addresses that are the result of DNS resolution of |
|
The receiver side via ActorCell.invoke() (inproc) or Actor.receive() (tcp) is represented by a span, with span.kind set to consumer.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | experimentalName of the top-level actor. See The Akka actor hierarchy 1 |
|
| string | experimentalPath to actor inside actor system. 2 |
|
| string | experimentalName of the actor system. 3 |
|
| string | experimentalFully qualified type name of actor. 4 |
|
| string | experimentalFully qualified type name of the message. |
|
| long | stableThe (uncompressed) size of the message payload in bytes. |
|
| string | stableFor Akka local, |
|
| string | stableLogical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. 5 |
|
| long | stableLogical server port number. 6 |
|
Unavailable in case of network.transport = tcp
Unavailable in case of network.transport = inproc
Unavailable in case of network.transport = inproc
Unavailable in case of network.transport = tcp
Unavailable in case of network.transport = inproc
Unavailable in case of network.transport = inproc
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.
| Value | Description | Display name |
|---|---|---|
| In-process communication. 1 | In-Process |
| Something else (non-IP-based). | Other |
| Named or anonymous pipe. | Pipe |
| TCP | TCP |
| UDP | UDP |
| Unix domain socket. | Unix Domain Socket |
Signals that there is only in-process communication not using a "real" network protocol in cases where network attributes would typically be expected. Usually, all other network attributes can be left out.
This convention extends the default semantic convention for messaging systems.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | stableString representation of the partition ID the message is sent to or received from. |
|
| string | experimentalThe |
|
| boolean | experimentalA boolean that is true if the message is a tombstone. 1 |
|
| long | experimentalThe offset of the message. |
|
If the message is a tombstone, the value is true. When missing, the value is assumed to be false.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | stableThe name of the consumer group with which a consumer is associated. 1 |
|
| string | stableString representation of the partition ID the message is sent to or received from. |
|
| string | experimentalThe |
|
| boolean | experimentalA boolean that is true if the message is a tombstone. 2 |
|
| long | experimentalThe offset of the message. |
|
Kafka consumer group ID
If the message is a tombstone, the value is true. When missing, the value is assumed to be false.
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | stableThe protocol that is used in the remote procedure call or web service. It can be omitted if it matches with |
|
| string | experimentalThe name of the (logical) method being called 1 |
|
| string | experimentalThe namespace of the method being called. In SOAP, it would be the XML namespace. |
|
| string | experimentalThe full (logical) name of the service being called, including its package name, if applicable. 2 |
|
| string | experimentalA string identifying the remoting system or framework. See below for a list of well-known identifiers. |
|
| string | stableLogical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. |
|
| long | stableLogical server port number. |
|
| ipAddress[] | stableA list of IP addresses that are the result of DNS resolution of |
|
This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The code.function attribute may be used to store the latter (e.g., method executing the call on the server side, RPC client stub method on the client side).
This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The code.namespace attribute may be used to store the latter (despite the attribute name, it may include a class name, e.g., class with method executing actually executing the call on the server side, RPC client stub class on the client side).
This span type represents an inbound RPC request.
For an RPC server span, SpanKind is Server.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | experimentalThe method or function name, or equivalent (usually the rightmost part of the code unit's name). Represents the name of the function that is represented by this span. 1 |
|
| string | experimentalLike |
|
| string | experimentalLike |
|
| string | experimentalThe namespace within which |
|
| string | stableOSI Transport Layer or Inter-process Communication method |
|
In the case of RPC, code.function represents the handler function that processes the RPC.
In the case of RPC, code.namespace represents the namespace of the handler function that processes the RPC.
Additional conventions for remote procedure calls via gRPC.
rpc.framework and rpc.protocol MUST be set to "grpc".
| Attribute | Type | Description | Examples |
|---|---|---|---|
| long | experimentalThe numeric status code of the gRPC request. |
Additional conventions for remote procedure calls via RMI.
rpc.framework and rpc.protocol MUST be set to "java-rmi".
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | experimentalThe URL of a rmi endpoint. |
|
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | resource experimentalThe name of the CICS program. 1 |
|
| string | experimentalThe z/OS Connect API description. |
|
| string | experimentalThe z/OS Connect API name. |
|
| string | experimentalThe z/OS Connect API version. |
|
| long | experimentalThe size of the request payload in bytes. |
|
| long | experimentalThe z/OS Connect request ID. |
|
| string | experimentalThe type of the REST request. 2 |
|
| long | experimentalThe size of the response payload in bytes. |
|
| string | experimentalThe z/OS Connect service description. |
|
| string | experimentalThe z/OS Connect service name. |
|
| string | experimentalThe service provider name. |
|
| string | experimentalThe z/OS Connect service version. |
|
| string | experimentalThe system of record identifier. The format differs depending on the SOR type. 3 |
|
| string | experimentalThe system of record reference. |
|
| string | experimentalIdentifier for the resource invoked on the system of record. The format differs depending on the SOR type. 4 |
|
| string | experimentalThe system of record type. |
|
Only applicable if zosconnect.sor.type is CICS
zosconnect.request.type MUST be one of the following:
| Value | Description | Display name |
|---|---|---|
| admin | Admin |
| api | API |
| service | Service |
| unknown | Unknown |
zosconnect.sor.type MUST be one of the following:
| Value | Description | Display name |
|---|---|---|
| cics | CICS |
| ims | IMS |
| mq | MQ |
| rest | REST |
| wola | WOLA |
The semantic conventions for z/OS client and server spans. You can use them for CICS and IMS schemes.
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.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | experimentalThe type of transaction call that was invoked. |
|
| string | resource experimentalThe jobname of the z/OS address space that the transaction executed in. |
|
| string | resource experimentalThe name of the LPAR that the transaction executed on. |
|
The common attributes of a CICS client/server transaction.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | resource experimentalThe system ID of the CICS region that this transaction executed on. |
|
| long | experimentalThe CICS task ID of this transaction. |
|
This span type represents an outbound CICS request.
For a CICS client span, span.kind is client.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | resource experimentalThe system ID of the server CICS region that will contain the started server transaction. |
|
| string | resource experimentalThe LPAR name that hosts the CICS region that will contain the started server transaction. |
|
This span type represents an inbound CICS request.
For a CICS server span, span.kind MUST be server.
| Attribute | Type | Description | Examples |
|---|---|---|---|
| string | resource experimentalThe system ID of the client CICS region that triggered this transaction. |
|
| string | resource experimentalThe LPAR name that hosts the client CICS region. |
|