diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index 626d8cc59f..ce0aed819c 100644 --- a/docs/attributes-registry/messaging.md +++ b/docs/attributes-registry/messaging.md @@ -3,9 +3,19 @@ # Messaging -## Messaging Attributes + - +- [Generic Messaging Attributes](#generic-messaging-attributes) +- [GCP Pub/Sub Attributes](#gcp-pub-sub-attributes) +- [Kafka Attributes](#kafka-attributes) +- [RabbitMQ Attributes](#rabbitmq-attributes) +- [RocketMQ Attributes](#rocketmq-attributes) + + + +## Generic Messaging Attributes + + | Attribute | Type | Description | Examples | |---|---|---|---| | `messaging.batch.message_count` | int | The number of messages sent, received, or processed in the scope of the batching operation. [1] | `0`; `1`; `2` | @@ -16,27 +26,11 @@ | `messaging.destination.temporary` | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | | `messaging.destination_publish.anonymous` | boolean | A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name). | | | `messaging.destination_publish.name` | string | The name of the original destination the message was published to [4] | `MyQueue`; `MyTopic` | -| `messaging.gcp_pubsub.message.ordering_key` | string | The ordering key for a given message. If the attribute is not present, the message does not have an ordering key. | `ordering_key` | -| `messaging.kafka.consumer.group` | string | Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. | `my-group` | -| `messaging.kafka.destination.partition` | int | Partition the message is sent to. | `2` | -| `messaging.kafka.message.key` | string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message.id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [5] | `myKey` | -| `messaging.kafka.message.offset` | int | The offset of a record in the corresponding Kafka partition. | `42` | -| `messaging.kafka.message.tombstone` | boolean | A boolean that is true if the message is a tombstone. | | -| `messaging.message.body.size` | int | The size of the message body in bytes. [6] | `1439` | +| `messaging.message.body.size` | int | The size of the message body in bytes. [5] | `1439` | | `messaging.message.conversation_id` | string | The conversation ID identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | -| `messaging.message.envelope.size` | int | The size of the message body and metadata in bytes. [7] | `2738` | +| `messaging.message.envelope.size` | int | The size of the message body and metadata in bytes. [6] | `2738` | | `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | -| `messaging.operation` | string | A string identifying the kind of messaging operation. [8] | `publish` | -| `messaging.rabbitmq.destination.routing_key` | string | RabbitMQ message routing key. | `myKey` | -| `messaging.rocketmq.client_group` | string | Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. | `myConsumerGroup` | -| `messaging.rocketmq.consumption_model` | string | Model of message consumption. This only applies to consumer spans. | `clustering` | -| `messaging.rocketmq.message.delay_time_level` | int | The delay time level for delay message, which determines the message delay time. | `3` | -| `messaging.rocketmq.message.delivery_timestamp` | int | The timestamp in milliseconds that the delay message is expected to be delivered to consumer. | `1665987217045` | -| `messaging.rocketmq.message.group` | string | It is essential for FIFO message. Messages that belong to the same message group are always processed one by one within the same consumer group. | `myMessageGroup` | -| `messaging.rocketmq.message.keys` | string[] | Key(s) of message, another way to mark message besides message id. | `[keyA, keyB]` | -| `messaging.rocketmq.message.tag` | string | The secondary classifier of message besides topic. | `tagA` | -| `messaging.rocketmq.message.type` | string | Type of message. | `normal` | -| `messaging.rocketmq.namespace` | string | Namespace of RocketMQ resources, resources in different namespaces are individual. | `myNamespace` | +| `messaging.operation` | string | A string identifying the kind of messaging operation. [7] | `publish` | | `messaging.system` | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `activemq` | **[1]:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs. @@ -49,15 +43,13 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi **[4]:** The name SHOULD uniquely identify a specific queue, topic, or other entity within the broker. If the broker doesn't have such notion, the original destination name SHOULD uniquely identify the broker. -**[5]:** If the key type is not string, it's string representation has to be supplied for the attribute. If the key has no unambiguous, canonical string form, don't include its value. - -**[6]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed +**[5]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed body size should be used. -**[7]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed +**[6]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed size should be used. -**[8]:** If a custom value is used, it MUST be of low cardinality. +**[7]:** If a custom value is used, it MUST be of low cardinality. `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. @@ -68,6 +60,67 @@ size should be used. | `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | | `deliver` | One or more messages are passed to a consumer. This operation refers to push-based scenarios, where consumer register callbacks which get called by messaging SDKs. | +`messaging.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `activemq` | Apache ActiveMQ | +| `aws_sqs` | Amazon Simple Queue Service (SQS) | +| `azure_eventgrid` | Azure Event Grid | +| `azure_eventhubs` | Azure Event Hubs | +| `azure_servicebus` | Azure Service Bus | +| `gcp_pubsub` | Google Cloud Pub/Sub | +| `jms` | Java Message Service | +| `kafka` | Apache Kafka | +| `rabbitmq` | RabbitMQ | +| `rocketmq` | Apache RocketMQ | + + +## GCP Pub/Sub Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `messaging.gcp_pubsub.message.ordering_key` | string | The ordering key for a given message. If the attribute is not present, the message does not have an ordering key. | `ordering_key` | + + +## Kafka Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `messaging.kafka.consumer.group` | string | Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. | `my-group` | +| `messaging.kafka.destination.partition` | int | Partition the message is sent to. | `2` | +| `messaging.kafka.message.key` | string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message.id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [1] | `myKey` | +| `messaging.kafka.message.offset` | int | The offset of a record in the corresponding Kafka partition. | `42` | +| `messaging.kafka.message.tombstone` | boolean | A boolean that is true if the message is a tombstone. | | + +**[1]:** If the key type is not string, it's string representation has to be supplied for the attribute. If the key has no unambiguous, canonical string form, don't include its value. + + +## RabbitMQ Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `messaging.rabbitmq.destination.routing_key` | string | RabbitMQ message routing key. | `myKey` | + + +## RocketMQ Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `messaging.rocketmq.client_group` | string | Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. | `myConsumerGroup` | +| `messaging.rocketmq.consumption_model` | string | Model of message consumption. This only applies to consumer spans. | `clustering` | +| `messaging.rocketmq.message.delay_time_level` | int | The delay time level for delay message, which determines the message delay time. | `3` | +| `messaging.rocketmq.message.delivery_timestamp` | int | The timestamp in milliseconds that the delay message is expected to be delivered to consumer. | `1665987217045` | +| `messaging.rocketmq.message.group` | string | It is essential for FIFO message. Messages that belong to the same message group are always processed one by one within the same consumer group. | `myMessageGroup` | +| `messaging.rocketmq.message.keys` | string[] | Key(s) of message, another way to mark message besides message id. | `[keyA, keyB]` | +| `messaging.rocketmq.message.tag` | string | The secondary classifier of message besides topic. | `tagA` | +| `messaging.rocketmq.message.type` | string | Type of message. | `normal` | +| `messaging.rocketmq.namespace` | string | Namespace of RocketMQ resources, resources in different namespaces are individual. | `myNamespace` | + `messaging.rocketmq.consumption_model` MUST be one of the following: | Value | Description | @@ -83,19 +136,4 @@ size should be used. | `fifo` | FIFO message | | `delay` | Delay message | | `transaction` | Transaction message | - -`messaging.system` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. - -| Value | Description | -|---|---| -| `activemq` | Apache ActiveMQ | -| `aws_sqs` | Amazon Simple Queue Service (SQS) | -| `azure_eventgrid` | Azure Event Grid | -| `azure_eventhubs` | Azure Event Hubs | -| `azure_servicebus` | Azure Service Bus | -| `gcp_pubsub` | Google Cloud Pub/Sub | -| `jms` | Java Message Service | -| `kafka` | Apache Kafka | -| `rabbitmq` | RabbitMQ | -| `rocketmq` | Apache RocketMQ | diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index c7ba8fd457..6f638976a3 100644 --- a/model/registry/messaging.yaml +++ b/model/registry/messaging.yaml @@ -12,11 +12,13 @@ groups: When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs. examples: [0, 1, 2] + tag: messaging-generic - id: client_id type: string brief: > A unique identifier for the client that consumes or produces a message. examples: ['client-5', 'myhost@8742@s8083jm'] + tag: messaging-generic - id: destination.name type: string brief: 'The message destination name' @@ -24,6 +26,7 @@ groups: Destination name SHOULD uniquely identify a specific queue, topic or other entity within the broker. If the broker doesn't have such notion, the destination name SHOULD uniquely identify the broker. examples: ['MyQueue', 'MyTopic'] + tag: messaging-generic - id: destination.template type: string brief: Low cardinality representation of the messaging destination name @@ -34,15 +37,19 @@ groups: the underlying template is of low cardinality and can be effectively used for grouping and aggregation. examples: ['/customers/{customerId}'] + tag: messaging-generic - id: destination.anonymous type: boolean brief: 'A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name).' + tag: messaging-generic - id: destination.temporary type: boolean brief: 'A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed.' + tag: messaging-generic - id: destination_publish.anonymous type: boolean brief: 'A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name).' + tag: messaging-generic - id: destination_publish.name type: string brief: 'The name of the original destination the message was published to' @@ -50,17 +57,20 @@ groups: The name SHOULD uniquely identify a specific queue, topic, or other entity within the broker. If the broker doesn't have such notion, the original destination name SHOULD uniquely identify the broker. examples: ['MyQueue', 'MyTopic'] + tag: messaging-generic - id: kafka.consumer.group type: string brief: > Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. examples: 'my-group' + tag: tech-specific-kafka - id: kafka.destination.partition type: int brief: > Partition the message is sent to. examples: 2 + tag: tech-specific-kafka - id: kafka.message.key type: string brief: > @@ -71,20 +81,24 @@ groups: If the key type is not string, it's string representation has to be supplied for the attribute. If the key has no unambiguous, canonical string form, don't include its value. examples: 'myKey' + tag: tech-specific-kafka - id: kafka.message.offset type: int brief: > The offset of a record in the corresponding Kafka partition. examples: 42 + tag: tech-specific-kafka - id: kafka.message.tombstone type: boolean brief: 'A boolean that is true if the message is a tombstone.' + tag: tech-specific-kafka - id: message.conversation_id type: string brief: > The conversation ID identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". examples: 'MyConversationId' + tag: messaging-generic - id: message.envelope.size type: int brief: > @@ -93,10 +107,12 @@ groups: This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed size should be used. examples: 2738 + tag: messaging-generic - id: message.id type: string brief: 'A value used by the messaging system as an identifier for the message, represented as a string.' examples: '452a7c7c7c7048c2f887f61572b18fc2' + tag: messaging-generic - id: message.body.size type: int brief: > @@ -105,6 +121,7 @@ groups: This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed body size should be used. examples: 1439 + tag: messaging-generic - id: operation type: allow_custom_values: true @@ -132,16 +149,19 @@ groups: brief: > A string identifying the kind of messaging operation. note: If a custom value is used, it MUST be of low cardinality. + tag: messaging-generic - id: rabbitmq.destination.routing_key type: string brief: > RabbitMQ message routing key. examples: 'myKey' + tag: tech-specific-rabbitmq - id: rocketmq.client_group type: string brief: > Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. examples: 'myConsumerGroup' + tag: tech-specific-rocketmq - id: rocketmq.consumption_model type: allow_custom_values: false @@ -154,31 +174,37 @@ groups: brief: 'Broadcasting consumption model' brief: > Model of message consumption. This only applies to consumer spans. + tag: tech-specific-rocketmq - id: rocketmq.message.delay_time_level type: int brief: > The delay time level for delay message, which determines the message delay time. examples: 3 + tag: tech-specific-rocketmq - id: rocketmq.message.delivery_timestamp type: int brief: > The timestamp in milliseconds that the delay message is expected to be delivered to consumer. examples: 1665987217045 + tag: tech-specific-rocketmq - id: rocketmq.message.group type: string brief: > It is essential for FIFO message. Messages that belong to the same message group are always processed one by one within the same consumer group. examples: 'myMessageGroup' + tag: tech-specific-rocketmq - id: rocketmq.message.keys type: string[] brief: > Key(s) of message, another way to mark message besides message id. examples: ['keyA', 'keyB'] + tag: tech-specific-rocketmq - id: rocketmq.message.tag type: string brief: > The secondary classifier of message besides topic. examples: tagA + tag: tech-specific-rocketmq - id: rocketmq.message.type type: allow_custom_values: false @@ -197,16 +223,19 @@ groups: brief: 'Transaction message' brief: > Type of message. + tag: tech-specific-rocketmq - id: rocketmq.namespace type: string brief: > Namespace of RocketMQ resources, resources in different namespaces are individual. examples: 'myNamespace' + tag: tech-specific-rocketmq - id: gcp_pubsub.message.ordering_key type: string brief: > The ordering key for a given message. If the attribute is not present, the message does not have an ordering key. examples: 'ordering_key' + tag: tech-specific-gcp-pubsub - id: system brief: > An identifier for the messaging system being used. See below for a list of well-known identifiers. @@ -243,3 +272,4 @@ groups: - id: rocketmq value: 'rocketmq' brief: 'Apache RocketMQ' + tag: messaging-generic