diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md index 92f7d4125c..a96d854871 100644 --- a/docs/messaging/messaging-metrics.md +++ b/docs/messaging/messaging-metrics.md @@ -41,23 +41,35 @@ 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.todo.status` | string | The status of the operation: TODO | `ok`; `error`; `timeout` | Required | -| `messaging.destination.name` | string | The message destination name [1] | `MyQueue`; `MyTopic` | Conditionally Required: [2] | -| `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [3] | `/customers/{customerId}` | Conditionally Required: if available. | +| `messaging.status.code` | string | The status of the operation. [1] | `OK`; `ERROR`; `TIMEOUT` | Required | +| `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 | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [5] | `3.1.1` | Recommended | | [`server.address`](../general/attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | Conditionally Required: If available. | | [`server.port`](../general/attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: If available. | | [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | -**[1]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If +**[1]:** If metric is reported alongside an messaging span, the `messaging.status.code` value SHOULD be identical to the span status. +Semantic convention extensions for specific messaging systems are encouraged to introduce messaging-system specific attribute +to record domain-specific error details. + +**[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. -**[2]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. +**[3]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. + +**[4]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. + +**[5]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[3]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. +`messaging.status.code` 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. -**[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +| Value | Description | +|---|---| +| `OK` | Operation succeeded. | +| `ERROR` | Operation failed. | +| `UNSET` | Operation result is not known. | ### Metric: `messaging.publish.messages` @@ -77,23 +89,35 @@ 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.todo.status` | string | The status of the operation: TODO | `ok`; `error`; `timeout` | Required | -| `messaging.destination.name` | string | The message destination name [1] | `MyQueue`; `MyTopic` | Conditionally Required: [2] | -| `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [3] | `/customers/{customerId}` | Conditionally Required: if available. | +| `messaging.status.code` | string | The status of the operation. [1] | `OK`; `ERROR`; `TIMEOUT` | Required | +| `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 | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [5] | `3.1.1` | Recommended | | [`server.address`](../general/attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | Conditionally Required: If available. | | [`server.port`](../general/attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: If available. | | [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | -**[1]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If +**[1]:** If metric is reported alongside an messaging span, the `messaging.status.code` value SHOULD be identical to the span status. +Semantic convention extensions for specific messaging systems are encouraged to introduce messaging-system specific attribute +to record domain-specific error details. + +**[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. -**[2]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. +**[3]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. + +**[4]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. + +**[5]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[3]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. +`messaging.status.code` 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. -**[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +| Value | Description | +|---|---| +| `OK` | Operation succeeded. | +| `ERROR` | Operation failed. | +| `UNSET` | Operation result is not known. | ## Consumer metrics @@ -114,23 +138,35 @@ When this metric is reported alongside an messaging receive span, the metric val | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Required | -| `messaging.todo.status` | string | The status of the operation: TODO | `ok`; `error`; `timeout` | Required | -| `messaging.destination.name` | string | The message destination name [1] | `MyQueue`; `MyTopic` | Conditionally Required: [2] | -| `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [3] | `/customers/{customerId}` | Conditionally Required: if available. | +| `messaging.status.code` | string | The status of the operation. [1] | `OK`; `ERROR`; `TIMEOUT` | Required | +| `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 | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [5] | `3.1.1` | Recommended | | [`server.address`](../general/attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | Conditionally Required: If available. | | [`server.port`](../general/attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: If available. | | [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | -**[1]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If +**[1]:** If metric is reported alongside an messaging span, the `messaging.status.code` value SHOULD be identical to the span status. +Semantic convention extensions for specific messaging systems are encouraged to introduce messaging-system specific attribute +to record domain-specific error details. + +**[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. -**[2]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. +**[3]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. + +**[4]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. + +**[5]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[3]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. +`messaging.status.code` 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. -**[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +| Value | Description | +|---|---| +| `OK` | Operation succeeded. | +| `ERROR` | Operation failed. | +| `UNSET` | Operation result is not known. | ### Metric: `messaging.receive.messages` @@ -149,23 +185,35 @@ _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.todo.status` | string | The status of the operation: TODO | `ok`; `error`; `timeout` | Required | -| `messaging.destination.name` | string | The message destination name [1] | `MyQueue`; `MyTopic` | Conditionally Required: [2] | -| `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [3] | `/customers/{customerId}` | Conditionally Required: if available. | +| `messaging.status.code` | string | The status of the operation. [1] | `OK`; `ERROR`; `TIMEOUT` | Required | +| `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 | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [5] | `3.1.1` | Recommended | | [`server.address`](../general/attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | Conditionally Required: If available. | | [`server.port`](../general/attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: If available. | | [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | -**[1]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If +**[1]:** If metric is reported alongside an messaging span, the `messaging.status.code` value SHOULD be identical to the span status. +Semantic convention extensions for specific messaging systems are encouraged to introduce messaging-system specific attribute +to record domain-specific error details. + +**[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. -**[2]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. +**[3]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. + +**[4]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. + +**[5]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[3]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. +`messaging.status.code` 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. -**[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +| Value | Description | +|---|---| +| `OK` | Operation succeeded. | +| `ERROR` | Operation failed. | +| `UNSET` | Operation result is not known. | ### Metric: `messaging.deliver.duration` @@ -184,23 +232,35 @@ When this metric is reported alongside an messaging deliver span, the metric val | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Required | -| `messaging.todo.status` | string | The status of the operation: TODO | `ok`; `error`; `timeout` | Required | -| `messaging.destination.name` | string | The message destination name [1] | `MyQueue`; `MyTopic` | Conditionally Required: [2] | -| `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [3] | `/customers/{customerId}` | Conditionally Required: if available. | +| `messaging.status.code` | string | The status of the operation. [1] | `OK`; `ERROR`; `TIMEOUT` | Required | +| `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 | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [5] | `3.1.1` | Recommended | | [`server.address`](../general/attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | Conditionally Required: If available. | | [`server.port`](../general/attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: If available. | | [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | -**[1]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If +**[1]:** If metric is reported alongside an messaging span, the `messaging.status.code` value SHOULD be identical to the span status. +Semantic convention extensions for specific messaging systems are encouraged to introduce messaging-system specific attribute +to record domain-specific error details. + +**[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. -**[2]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. +**[3]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. + +**[4]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. + +**[5]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[3]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. +`messaging.status.code` 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. -**[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +| Value | Description | +|---|---| +| `OK` | Operation succeeded. | +| `ERROR` | Operation failed. | +| `UNSET` | Operation result is not known. | ### Metric: `messaging.deliver.messages` @@ -219,23 +279,35 @@ _Note: The need to report `messaging.deliver.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.todo.status` | string | The status of the operation: TODO | `ok`; `error`; `timeout` | Required | -| `messaging.destination.name` | string | The message destination name [1] | `MyQueue`; `MyTopic` | Conditionally Required: [2] | -| `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [3] | `/customers/{customerId}` | Conditionally Required: if available. | +| `messaging.status.code` | string | The status of the operation. [1] | `OK`; `ERROR`; `TIMEOUT` | Required | +| `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 | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [5] | `3.1.1` | Recommended | | [`server.address`](../general/attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | Conditionally Required: If available. | | [`server.port`](../general/attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: If available. | | [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | -**[1]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If +**[1]:** If metric is reported alongside an messaging span, the `messaging.status.code` value SHOULD be identical to the span status. +Semantic convention extensions for specific messaging systems are encouraged to introduce messaging-system specific attribute +to record domain-specific error details. + +**[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. -**[2]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. +**[3]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. + +**[4]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. + +**[5]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[3]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. +`messaging.status.code` 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. -**[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +| Value | Description | +|---|---| +| `OK` | Operation succeeded. | +| `ERROR` | Operation failed. | +| `UNSET` | Operation result is not known. | ### Metric: `messaging.settle.duration` @@ -254,24 +326,36 @@ When this metric is reported alongside an messaging settle 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.todo.status` | string | The status of the operation: TODO | `ok`; `error`; `timeout` | Required | +| `messaging.status.code` | string | The status of the operation. [1] | `OK`; `ERROR`; `TIMEOUT` | Required | | `messaging.todo_settlement.status` | string | The status of the settlement: acknowledged, rejected, TODO | `ack`; `nack` | Recommended | -| `messaging.destination.name` | string | The message destination name [1] | `MyQueue`; `MyTopic` | Conditionally Required: [2] | -| `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [3] | `/customers/{customerId}` | Conditionally Required: if available. | +| `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 | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [5] | `3.1.1` | Recommended | | [`server.address`](../general/attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | Conditionally Required: If available. | | [`server.port`](../general/attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: If available. | | [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | -**[1]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If +**[1]:** If metric is reported alongside an messaging span, the `messaging.status.code` value SHOULD be identical to the span status. +Semantic convention extensions for specific messaging systems are encouraged to introduce messaging-system specific attribute +to record domain-specific error details. + +**[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. -**[2]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. +**[3]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. + +**[4]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. + +**[5]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[3]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. +`messaging.status.code` 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. -**[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +| Value | Description | +|---|---| +| `OK` | Operation succeeded. | +| `ERROR` | Operation failed. | +| `UNSET` | Operation result is not known. | ### Metric: `messaging.settle.messages` @@ -290,23 +374,35 @@ _Note: The need to report `messaging.settle.messages` depends on the messaging s | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Required | -| `messaging.todo.status` | string | The status of the operation: TODO | `ok`; `error`; `timeout` | Required | -| `messaging.destination.name` | string | The message destination name [1] | `MyQueue`; `MyTopic` | Conditionally Required: [2] | -| `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [3] | `/customers/{customerId}` | Conditionally Required: if available. | +| `messaging.status.code` | string | The status of the operation. [1] | `OK`; `ERROR`; `TIMEOUT` | Required | +| `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 | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [5] | `3.1.1` | Recommended | | [`server.address`](../general/attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | Conditionally Required: If available. | | [`server.port`](../general/attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: If available. | | [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | -**[1]:** Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If +**[1]:** If metric is reported alongside an messaging span, the `messaging.status.code` value SHOULD be identical to the span status. +Semantic convention extensions for specific messaging systems are encouraged to introduce messaging-system specific attribute +to record domain-specific error details. + +**[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. -**[2]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. +**[3]:** if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. + +**[4]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. + +**[5]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[3]:** Destination names could be constructed from templates. An example would be a destination name involving a user name or product id. Although the destination name in this case is of high cardinality, the underlying template is of low cardinality and can be effectively used for grouping and aggregation. +`messaging.status.code` 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. -**[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +| Value | Description | +|---|---| +| `OK` | Operation succeeded. | +| `ERROR` | Operation failed. | +| `UNSET` | Operation result is not known. | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md diff --git a/model/metrics/messaging.yaml b/model/metrics/messaging.yaml index 0c268375aa..0ffa978063 100644 --- a/model/metrics/messaging.yaml +++ b/model/metrics/messaging.yaml @@ -10,11 +10,26 @@ groups: - ref: messaging.destination.template requirement_level: conditionally_required: if available. - - id: messaging.todo.status - type: string - brief: "The status of the operation: TODO" + - id: messaging.status.code + type: + allow_custom_values: true + members: + - id: ok + value: "OK" + brief: 'Operation succeeded.' + - id: error + value: "ERROR" + brief: 'Operation failed.' + - id: unset + value: "UNSET" + brief: 'Operation result is not known.' + brief: "The status of the operation." requirement_level: required - examples: ["ok", "error", "timeout"] + examples: ["OK", "ERROR", "TIMEOUT"] + note: | + If metric is reported alongside an messaging span, the `messaging.status.code` value SHOULD be identical to the span status. + Semantic convention extensions for specific messaging systems are encouraged to introduce messaging-system specific attribute + to record domain-specific error details. # durations - id: metric.messaging.publish.duration