From 034ff58ecbec0e76682504839d593699ad6298a8 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 23 Aug 2023 15:51:49 -0700 Subject: [PATCH] update to error.id --- docs/messaging/messaging-metrics.md | 76 +++++++++++++++++------------ docs/messaging/messaging-spans.md | 43 ++++++++-------- model/error.yaml | 33 +++++++++++++ model/trace/messaging.yaml | 24 +-------- 4 files changed, 101 insertions(+), 75 deletions(-) create mode 100644 model/error.yaml diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md index 410abf878e..452d0c1f24 100644 --- a/docs/messaging/messaging-metrics.md +++ b/docs/messaging/messaging-metrics.md @@ -41,7 +41,7 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Required | -| `messaging.error.description` | string | Describes a class of error messaging operation has ended with. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | Conditionally Required: If the messaging operation has failed. | +| `error.id` | string | Describes a class of error the operation ended with. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | Conditionally Required: If the messaging operation has failed. | | `messaging.destination.name` | string | The message destination name [2] | `MyQueue`; `MyTopic` | Conditionally Required: [3] | | `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [4] | `/customers/{customerId}` | Conditionally Required: if available. | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `mqtt` | Recommended | @@ -52,15 +52,19 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, **[1]:** TODO - https://github.com/open-telemetry/semantic-conventions/pull/205 -The error description SHOULD be predictable and SHOULD have low cardinality. +The `error.id` SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. -The cardinality of error description within one instrumentation library SHOULD be low, but +The cardinality of `error.id` within one instrumentation library SHOULD be low, but telemetry consumers that aggregate data from multiple instrumentation libraries and applications -should be prepared for `error.description` to have high cardinality at query time, when no +should be prepared for `error.id` to have high cardinality at query time, when no additional filters are applied. -If operation has completed successfully, instrumentations SHOULD NOT set `error.description`. +If the operation has completed successfully, instrumentations SHOULD NOT set `error.id`. + +If a specific domain defines its own set of error codes (such as HTTP or gRPC status codes), +it's RECOMMENDED to use a domain-specific attribute and also set `error.id` to capture +all errors, regardless of whether they are defined within the domain-specific set or not. **[2]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If the broker does not have such notion, the destination name SHOULD uniquely identify the broker. @@ -79,12 +83,11 @@ the server address behind any intermediaries (e.g. proxies) if it's available. **[8]:** When observed from the client side, this SHOULD represent the immediate server peer address. When observed from the server side, this SHOULD represent the physical server address. -`messaging.error.description` 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. +`error.id` 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 | |---|---| -| `` | No error. Default value. | -| `_OTHER` | Any error reason instrumentation does not define custom value for. | +| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | ### Metric: `messaging.publish.messages` @@ -104,7 +107,7 @@ For example, RabbitMQ does not support batch publishing and corresponding instru | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Required | -| `messaging.error.description` | string | Describes a class of error messaging operation has ended with. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | Conditionally Required: If the messaging operation has failed. | +| `error.id` | string | Describes a class of error the operation ended with. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | Conditionally Required: If the messaging operation has failed. | | `messaging.destination.name` | string | The message destination name [2] | `MyQueue`; `MyTopic` | Conditionally Required: [3] | | `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [4] | `/customers/{customerId}` | Conditionally Required: if available. | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `mqtt` | Recommended | @@ -115,15 +118,19 @@ For example, RabbitMQ does not support batch publishing and corresponding instru **[1]:** TODO - https://github.com/open-telemetry/semantic-conventions/pull/205 -The error description SHOULD be predictable and SHOULD have low cardinality. +The `error.id` SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. -The cardinality of error description within one instrumentation library SHOULD be low, but +The cardinality of `error.id` within one instrumentation library SHOULD be low, but telemetry consumers that aggregate data from multiple instrumentation libraries and applications -should be prepared for `error.description` to have high cardinality at query time, when no +should be prepared for `error.id` to have high cardinality at query time, when no additional filters are applied. -If operation has completed successfully, instrumentations SHOULD NOT set `error.description`. +If the operation has completed successfully, instrumentations SHOULD NOT set `error.id`. + +If a specific domain defines its own set of error codes (such as HTTP or gRPC status codes), +it's RECOMMENDED to use a domain-specific attribute and also set `error.id` to capture +all errors, regardless of whether they are defined within the domain-specific set or not. **[2]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If the broker does not have such notion, the destination name SHOULD uniquely identify the broker. @@ -142,12 +149,11 @@ the server address behind any intermediaries (e.g. proxies) if it's available. **[8]:** When observed from the client side, this SHOULD represent the immediate server peer address. When observed from the server side, this SHOULD represent the physical server address. -`messaging.error.description` 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. +`error.id` 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 | |---|---| -| `` | No error. Default value. | -| `_OTHER` | Any error reason instrumentation does not define custom value for. | +| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | ## Consumer metrics @@ -168,7 +174,7 @@ When this metric is reported alongside a messaging receive span, the metric valu | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Required | -| `messaging.error.description` | string | Describes a class of error messaging operation has ended with. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | Conditionally Required: If the messaging operation has failed. | +| `error.id` | string | Describes a class of error the operation ended with. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | Conditionally Required: If the messaging operation has failed. | | `messaging.destination.name` | string | The message destination name [2] | `MyQueue`; `MyTopic` | Conditionally Required: [3] | | `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [4] | `/customers/{customerId}` | Conditionally Required: if available. | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `mqtt` | Recommended | @@ -179,15 +185,19 @@ When this metric is reported alongside a messaging receive span, the metric valu **[1]:** TODO - https://github.com/open-telemetry/semantic-conventions/pull/205 -The error description SHOULD be predictable and SHOULD have low cardinality. +The `error.id` SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. -The cardinality of error description within one instrumentation library SHOULD be low, but +The cardinality of `error.id` within one instrumentation library SHOULD be low, but telemetry consumers that aggregate data from multiple instrumentation libraries and applications -should be prepared for `error.description` to have high cardinality at query time, when no +should be prepared for `error.id` to have high cardinality at query time, when no additional filters are applied. -If operation has completed successfully, instrumentations SHOULD NOT set `error.description`. +If the operation has completed successfully, instrumentations SHOULD NOT set `error.id`. + +If a specific domain defines its own set of error codes (such as HTTP or gRPC status codes), +it's RECOMMENDED to use a domain-specific attribute and also set `error.id` to capture +all errors, regardless of whether they are defined within the domain-specific set or not. **[2]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If the broker does not have such notion, the destination name SHOULD uniquely identify the broker. @@ -206,12 +216,11 @@ the server address behind any intermediaries (e.g. proxies) if it's available. **[8]:** When observed from the client side, this SHOULD represent the immediate server peer address. When observed from the server side, this SHOULD represent the physical server address. -`messaging.error.description` 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. +`error.id` 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 | |---|---| -| `` | No error. Default value. | -| `_OTHER` | Any error reason instrumentation does not define custom value for. | +| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | ### Metric: `messaging.receive.messages` @@ -230,7 +239,7 @@ _Note: The need to report `messaging.receive.messages` depends on the messaging | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Required | -| `messaging.error.description` | string | Describes a class of error messaging operation has ended with. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | Conditionally Required: If the messaging operation has failed. | +| `error.id` | string | Describes a class of error the operation ended with. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | Conditionally Required: If the messaging operation has failed. | | `messaging.destination.name` | string | The message destination name [2] | `MyQueue`; `MyTopic` | Conditionally Required: [3] | | `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [4] | `/customers/{customerId}` | Conditionally Required: if available. | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `mqtt` | Recommended | @@ -241,15 +250,19 @@ _Note: The need to report `messaging.receive.messages` depends on the messaging **[1]:** TODO - https://github.com/open-telemetry/semantic-conventions/pull/205 -The error description SHOULD be predictable and SHOULD have low cardinality. +The `error.id` SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. -The cardinality of error description within one instrumentation library SHOULD be low, but +The cardinality of `error.id` within one instrumentation library SHOULD be low, but telemetry consumers that aggregate data from multiple instrumentation libraries and applications -should be prepared for `error.description` to have high cardinality at query time, when no +should be prepared for `error.id` to have high cardinality at query time, when no additional filters are applied. -If operation has completed successfully, instrumentations SHOULD NOT set `error.description`. +If the operation has completed successfully, instrumentations SHOULD NOT set `error.id`. + +If a specific domain defines its own set of error codes (such as HTTP or gRPC status codes), +it's RECOMMENDED to use a domain-specific attribute and also set `error.id` to capture +all errors, regardless of whether they are defined within the domain-specific set or not. **[2]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If the broker does not have such notion, the destination name SHOULD uniquely identify the broker. @@ -268,12 +281,11 @@ the server address behind any intermediaries (e.g. proxies) if it's available. **[8]:** When observed from the client side, this SHOULD represent the immediate server peer address. When observed from the server side, this SHOULD represent the physical server address. -`messaging.error.description` 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. +`error.id` 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 | |---|---| -| `` | No error. Default value. | -| `_OTHER` | Any error reason instrumentation does not define custom value for. | +| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index ff03a2808a..bcafae2e6f 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -217,10 +217,10 @@ The following operations related to messages are defined for these semantic conv | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Required | -| `messaging.error.description` | string | Describes a class of error messaging operation has ended with. [1] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | Conditionally Required: If the messaging operation has failed. | -| `messaging.operation` | string | A string identifying the kind of messaging operation as defined in the [Operation names](#operation-names) section above. [2] | `publish` | Required | -| `messaging.batch.message_count` | int | The number of messages sent, received, or processed in the scope of the batching operation. [3] | `0`; `1`; `2` | Conditionally Required: [4] | +| `messaging.operation` | string | A string identifying the kind of messaging operation as defined in the [Operation names](#operation-names) section above. [1] | `publish` | Required | +| `messaging.batch.message_count` | int | The number of messages sent, received, or processed in the scope of the batching operation. [2] | `0`; `1`; `2` | Conditionally Required: [3] | | `messaging.client_id` | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | Recommended: If a client id is available | +| `error.id` | string | Describes a class of error the operation ended with. [4] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | Conditionally Required: If the messaging operation has failed. | | `messaging.destination.anonymous` | boolean | A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name). | | Conditionally Required: [5] | | `messaging.destination.name` | string | The message destination name [6] | `MyQueue`; `MyTopic` | Conditionally Required: [7] | | `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [8] | `/customers/{customerId}` | Conditionally Required: [9] | @@ -239,23 +239,27 @@ The following operations related to messages are defined for these semantic conv | [`server.socket.domain`](../general/attributes.md) | string | Immediate server peer's domain name if available without reverse DNS lookup [19] | `proxy.example.com` | Recommended: [20] | | [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [21] | `16456` | Recommended: If different than `server.port`. | -**[1]:** TODO - https://github.com/open-telemetry/semantic-conventions/pull/205 +**[1]:** If a custom value is used, it MUST be of low cardinality. -The error description SHOULD be predictable and SHOULD have low cardinality. +**[2]:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs. + +**[3]:** If the span describes an operation on a batch of messages. + +**[4]:** TODO - https://github.com/open-telemetry/semantic-conventions/pull/205 + +The `error.id` SHOULD be predictable and SHOULD have low cardinality. Instrumentations SHOULD document the list of errors they report. -The cardinality of error description within one instrumentation library SHOULD be low, but +The cardinality of `error.id` within one instrumentation library SHOULD be low, but telemetry consumers that aggregate data from multiple instrumentation libraries and applications -should be prepared for `error.description` to have high cardinality at query time, when no +should be prepared for `error.id` to have high cardinality at query time, when no additional filters are applied. -If operation has completed successfully, instrumentations SHOULD NOT set `error.description`. - -**[2]:** If a custom value is used, it MUST be of low cardinality. +If the operation has completed successfully, instrumentations SHOULD NOT set `error.id`. -**[3]:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs. - -**[4]:** If the span describes an operation on a batch of messages. +If a specific domain defines its own set of error codes (such as HTTP or gRPC status codes), +it's RECOMMENDED to use a domain-specific attribute and also set `error.id` to capture +all errors, regardless of whether they are defined within the domain-specific set or not. **[5]:** If value is `true`. When missing, the value is assumed to be `false`. @@ -295,13 +299,6 @@ When observed from the server side, this SHOULD represent the physical server ad **[21]:** When observed from the client side, this SHOULD represent the immediate server peer port. When observed from the server side, this SHOULD represent the physical server port. -`messaging.error.description` 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 | -|---|---| -| `` | No error. Default value. | -| `_OTHER` | Any error reason instrumentation does not define custom value for. | - `messaging.operation` 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 | @@ -310,6 +307,12 @@ When observed from the server side, this SHOULD represent the physical server po | `receive` | receive | | `process` | process | +`error.id` 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 | +|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation does not define a custom value for it. | + `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 | diff --git a/model/error.yaml b/model/error.yaml new file mode 100644 index 0000000000..038416d8c7 --- /dev/null +++ b/model/error.yaml @@ -0,0 +1,33 @@ +groups: + - id: error + type: attribute_group + prefix: error + brief: > + This document defines the shared attributes used to + report an error. + attributes: + - id: id + brief: 'Describes a class of error the operation ended with.' + type: + allow_custom_values: true + members: + - id: other + value: "_OTHER" + brief: 'A fallback error value to be used when the instrumentation does not define a custom value for it.' + examples: ['timeout', 'java.net.UnknownHostException', 'server_certificate_invalid', 'Internal Server Error'] + note: | + TODO - https://github.com/open-telemetry/semantic-conventions/pull/205 + + The `error.id` SHOULD be predictable and SHOULD have low cardinality. + Instrumentations SHOULD document the list of errors they report. + + The cardinality of `error.id` within one instrumentation library SHOULD be low, but + telemetry consumers that aggregate data from multiple instrumentation libraries and applications + should be prepared for `error.id` to have high cardinality at query time, when no + additional filters are applied. + + If the operation has completed successfully, instrumentations SHOULD NOT set `error.id`. + + If a specific domain defines its own set of error codes (such as HTTP or gRPC status codes), + it's RECOMMENDED to use a domain-specific attribute and also set `error.id` to capture + all errors, regardless of whether they are defined within the domain-specific set or not. \ No newline at end of file diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index 65f36cfd13..12d2eba983 100644 --- a/model/trace/messaging.yaml +++ b/model/trace/messaging.yaml @@ -102,32 +102,10 @@ groups: requirement_level: required brief: 'A string identifying the messaging system.' examples: ['kafka', 'rabbitmq', 'rocketmq', 'activemq', 'AmazonSQS'] - - id: error.description - brief: 'Describes a class of error messaging operation has ended with.' - type: - allow_custom_values: true - members: - - id: empty - value: "" - brief: 'No error. Default value.' - - id: other - value: "_OTHER" - brief: 'Any error reason instrumentation does not define custom value for.' + - ref: error.id examples: ['amqp:decode-error', 'KAFKA_STORAGE_ERROR', 'channel-error'] requirement_level: conditionally_required: If the messaging operation has failed. - note: | - TODO - https://github.com/open-telemetry/semantic-conventions/pull/205 - - The error description SHOULD be predictable and SHOULD have low cardinality. - Instrumentations SHOULD document the list of errors they report. - - The cardinality of error description within one instrumentation library SHOULD be low, but - telemetry consumers that aggregate data from multiple instrumentation libraries and applications - should be prepared for `error.description` to have high cardinality at query time, when no - additional filters are applied. - - If operation has completed successfully, instrumentations SHOULD NOT set `error.description`. - ref: server.address requirement_level: conditionally_required: If available.