update to error.id

open-telemetry · Aug 23, 2023 · 034ff58 · 034ff58
1 parent 520c483
commit 034ff58
Show file tree

Hide file tree

Showing 4 changed files with 101 additions and 75 deletions.
diff --git 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. |
 <!-- endsemconv -->
 
 ### 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. |
 <!-- endsemconv -->
 
 ## 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. |
 <!-- endsemconv -->
 
 ### 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. |
 <!-- endsemconv -->