diff --git a/semantic_conventions/metrics/messaging.yaml b/semantic_conventions/metrics/messaging.yaml new file mode 100644 index 0000000000..5411fb0ca7 --- /dev/null +++ b/semantic_conventions/metrics/messaging.yaml @@ -0,0 +1,82 @@ +groups: + - id: metric.messaging.attributes + type: attribute_group + brief: "Common messaging metrics attributes." + extends: messaging.attributes.common + attributes: + - ref: messaging.destination.name + requirement_level: + conditionally_required: if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated. + - ref: messaging.destination.template + requirement_level: + conditionally_required: if available. + - id: messaging.todo.status + type: string + brief: "The status of the operation: TODO" + requirement_level: required + examples: ["ok", "error", "timeout"] + +# duration + + - id: metric.messaging.publish.duration + type: metric + metric_name: messaging.publish.duration + brief: "Measures the duration of publish operation." + instrument: histogram + unit: "s" + extends: metric.messaging.attributes + + - id: metric.messaging.receive.duration + type: metric + metric_name: messaging.receive.duration + brief: "Measures the duration of receive operation." + instrument: histogram + unit: "s" + extends: metric.messaging.attributes + + - id: metric.messaging.deliver.duration + type: metric + metric_name: messaging.deliver.duration + brief: "Measures the duration of deliver operation." + instrument: histogram + unit: "s" + extends: metric.messaging.attributes + + - id: metric.messaging.settle.duration + type: metric + metric_name: messaging.settle.duration + brief: "Measures the duration of settle operation." + instrument: histogram + unit: "s" + extends: metric.messaging.attributes + attributes: + - id: messaging.todo_settlement.status + type: string + brief: "The status of the settlement: acknowledged, rejected, TODO" + examples: ["ack", "nack"] + +# count + + - id: metric.messaging.publish.count + type: metric + metric_name: messaging.published_messages.count + brief: "Measures the number of published messages." + instrument: counter + unit: "message" + extends: metric.messaging.attributes + + - id: metric.messaging.receive.count + type: metric + metric_name: messaging.received_messages.count + brief: "Measures the number of received or delivered messages." + instrument: counter + unit: "message" + extends: metric.messaging.attributes + + - id: metric.messaging.settle.count + type: metric + metric_name: messaging.settled_messages.count + brief: "Measures the number of settled messages." + instrument: counter + unit: "message" + extends: metric.messaging.attributes \ No newline at end of file diff --git a/semantic_conventions/trace/messaging.yaml b/semantic_conventions/trace/messaging.yaml index 5df3c54698..a042a86988 100644 --- a/semantic_conventions/trace/messaging.yaml +++ b/semantic_conventions/trace/messaging.yaml @@ -64,18 +64,36 @@ groups: type: boolean brief: 'A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name).' - - id: messaging + - id: messaging.attributes.common + type: attribute_group + brief: "Common messaging attributes." prefix: messaging - type: span - brief: > - This document defines general attributes used in - messaging systems. attributes: - id: system type: string requirement_level: required brief: 'A string identifying the messaging system.' examples: ['kafka', 'rabbitmq', 'rocketmq', 'activemq', 'AmazonSQS'] + - ref: server.address + requirement_level: + conditionally_required: If available. + - ref: server.port + requirement_level: + conditionally_required: If available. + - ref: server.socket.address + tag: connection-level + - ref: network.protocol.name + examples: ['amqp', 'mqtt'] + - ref: network.protocol.version + + - id: messaging + prefix: messaging + type: span + brief: > + This document defines general attributes used in + messaging systems. + extends: messaging.attributes.common + attributes: - id: operation type: allow_custom_values: true @@ -134,13 +152,6 @@ groups: - ref: messaging.message.payload_compressed_size_bytes requirement_level: recommended: Only if span represents operation on a single message. - - ref: server.address - note: > - This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. - requirement_level: - conditionally_required: If available. - - ref: server.socket.address - tag: connection-level - ref: server.socket.port tag: connection-level - ref: network.transport @@ -151,9 +162,6 @@ groups: tag: connection-level requirement_level: recommended: If different than `server.address` and if `server.socket.address` is set. - - ref: network.protocol.name - examples: ['amqp', 'mqtt'] - - ref: network.protocol.version - id: messaging.rabbitmq prefix: messaging.rabbitmq diff --git a/specification/messaging/messaging-metrics.md b/specification/messaging/messaging-metrics.md new file mode 100644 index 0000000000..1837de7bd3 --- /dev/null +++ b/specification/messaging/messaging-metrics.md @@ -0,0 +1,260 @@ +# Semantic Conventions for Messaging Metrics + +**Status**: [Experimental][DocumentStatus] + + + + + + + +# Semantic Conventions for Messaging Metrics + +**Status**: [Experimental][DocumentStatus] + +The conventions described in this section are messaging specific. + +**Disclaimer:** These are initial messaging metric instruments and attributes but more may be added in the future. + + + + +## Metric: `messaging.publish.duration` + +This metric is required. + +When this metric is reported alongside an messaging publish span, the metric value SHOULD be the same as the corresponding span duration. + +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/metrics/api.md#instrument-advice) +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, 10 ]`. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `messaging.publish.duration` | Histogram | `s` | Measures the duration of publish operation. | + + + +| 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. | +| [`network.protocol.name`](../general/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/general-attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`server.address`](../general/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/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: If available. | +| [`server.socket.address`](../general/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 +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]:** 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. + +**[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`. + + +## Metric: `messaging.receive.duration` + +This metric is recommended when messaging system supports poll-based receive operations. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `messaging.receive.duration` | Histogram | `s` | Measures the duration of receive operation. | + + + +| 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. | +| [`network.protocol.name`](../general/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/general-attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`server.address`](../general/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/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: If available. | +| [`server.socket.address`](../general/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 +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]:** 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. + +**[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`. + + +## Metric: `messaging.deliver.duration` + +This metric is recommended when messaging system supports pull-based deliver operations. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `messaging.deliver.duration` | Histogram | `s` | Measures the duration of deliver operation. | + + + +| 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. | +| [`network.protocol.name`](../general/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/general-attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`server.address`](../general/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/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: If available. | +| [`server.socket.address`](../general/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 +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]:** 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. + +**[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`. + + +## Metric: `messaging.settle.duration` + +This metric is recommended when messaging system supports settle operations. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `messaging.settle.duration` | Histogram | `s` | Measures the duration of settle operation. | + + + +| 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.todo_settlement.status`](../system/messaging-metrics.md) | 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. | +| [`network.protocol.name`](../general/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/general-attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`server.address`](../general/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/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: If available. | +| [`server.socket.address`](../general/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 +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]:** 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. + +**[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`. + + +## Metric: `messaging.published_messages.count` + +This metric is recommended when messaging system supports batch publishing. For the systems that support single-message publishing only, message count can be derived from `messaging.publish.duration` histogram. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `messaging.published_messages.count` | Counter | `message` | Measures the number of published messages. | + + + +| 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. | +| [`network.protocol.name`](../general/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/general-attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`server.address`](../general/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/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: If available. | +| [`server.socket.address`](../general/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 +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]:** 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. + +**[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`. + + +## Metric: `messaging.received_messages.count` + +This metric is recommended when messaging system supports batch receive. For the systems that can only receive one message, message count can be derived from `messaging.receive.duration` or `messaging.deliver.duration` histogram. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `messaging.received_messages.count` | Counter | `message` | Measures the number of received or delivered messages. | + + + +| 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. | +| [`network.protocol.name`](../general/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/general-attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`server.address`](../general/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/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: If available. | +| [`server.socket.address`](../general/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 +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]:** 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. + +**[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`. + + +## Metric: `messaging.settled_messages.count` + +This metric is recommended when messaging system supports per-message batch settlement. For the systems that can only settle individual messages, message count can be derived from `messaging.settle.duration` histogram. Systems that support offset-based settlement, SHOULD NOT report this metric. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `messaging.settled_messages.count` | Counter | `message` | Measures the number of settled messages. | + + + +| 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. | +| [`network.protocol.name`](../general/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/general-attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`server.address`](../general/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/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: If available. | +| [`server.socket.address`](../general/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 +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]:** 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. + +**[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`. + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md diff --git a/specification/messaging/messaging-spans.md b/specification/messaging/messaging-spans.md index dbabf55627..76953156c0 100644 --- a/specification/messaging/messaging-spans.md +++ b/specification/messaging/messaging-spans.md @@ -1,4 +1,4 @@ -# Messaging systems +# Tracing Semantic Conventions for Messaging **Status**: [Experimental][DocumentStatus] @@ -206,7 +206,7 @@ The following operations related to messages are defined for these semantic conv ## Messaging attributes - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Required | @@ -225,9 +225,10 @@ The following operations related to messages are defined for these semantic conv | [`network.protocol.version`](../general/general-attributes.md) | string | Version of the application layer protocol used. See note below. [14] | `3.1.1` | Recommended | | [`network.transport`](../general/general-attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | | [`network.type`](../general/general-attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../general/general-attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. [15] | `example.com` | Conditionally Required: If available. | +| [`server.address`](../general/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/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: If available. | | [`server.socket.address`](../general/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`. | -| [`server.socket.domain`](../general/general-attributes.md) | string | The domain name of an immediate peer. [16] | `proxy.example.com` | Recommended: [17] | +| [`server.socket.domain`](../general/general-attributes.md) | string | The domain name of an immediate peer. [15] | `proxy.example.com` | Recommended: [16] | | [`server.socket.port`](../general/general-attributes.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | **[1]:** If a custom value is used, it MUST be of low cardinality. @@ -259,11 +260,9 @@ the broker does not have such notion, the destination name SHOULD uniquely ident **[14]:** `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`. -**[15]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. +**[15]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. -**[16]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. - -**[17]:** If different than `server.address` and if `server.socket.address` is set. +**[16]:** If different than `server.address` and if `server.socket.address` is set. `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. @@ -272,6 +271,22 @@ the broker does not have such notion, the destination name SHOULD uniquely ident | `publish` | publish | | `receive` | receive | | `process` | process | + +`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 | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + +`network.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 | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | Additionally `server.port` from the [network attributes][] is recommended. diff --git a/specification/system/messaging-metrics.md b/specification/system/messaging-metrics.md new file mode 100644 index 0000000000..c719521de4 --- /dev/null +++ b/specification/system/messaging-metrics.md @@ -0,0 +1,126 @@ + + +# Semantic Conventions for Messaging Metrics + +**Status**: [Experimental][DocumentStatus] + +The conventions described in this section are messaging specific. + +**Disclaimer:** These are initial messaging metric instruments and attributes but more may be added in the future. + + + + +## Metric: `messaging.publish.duration` + +This metric is required. + +When this metric is reported alongside an messaging publish span, the metric value SHOULD be the same as the corresponding span duration. + +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/metrics/api.md#instrument-advice) +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, 10 ]`. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `messaging.publish.duration` | Histogram | `s` | Measures the duration of publish operation. | + + + +| 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. | +| [`network.protocol.name`](../general/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/general-attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`server.address`](../general/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/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: If available. | +| [`server.socket.address`](../general/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 +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]:** 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. + +**[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`. + + +## Metric: `messaging.receive.duration` + +This metric is recommended when messaging system supports poll-based receive operations. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `messaging.receive.duration` | Histogram | `s` | Measures the duration of receive operation. | + + + +| 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. | +| [`network.protocol.name`](../general/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/general-attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`server.address`](../general/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/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: If available. | +| [`server.socket.address`](../general/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 +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]:** 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. + +**[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`. + + + +## Metric: `messaging.settle.duration` + +This metric is recommended when messaging system supports settle operations. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `messaging.settle.duration` | Histogram | `s` | Measures the duration of settle operation. | + + + +| 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.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. | +| [`network.protocol.name`](../general/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/general-attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `3.1.1` | Recommended | +| [`server.address`](../general/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/general-attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: If available. | +| [`server.socket.address`](../general/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 +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]:** 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. + +**[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`. + + +## Others: + +- batch size (payload, in bytes): probably transport-level concept, not necessary here +- consumer lag/queue size - need to define new attributes (enqueue/creation time)