Skip to content

Commit

Permalink
Move messaging attributes in registry to system-specific sections
Browse files Browse the repository at this point in the history
  • Loading branch information
@pyohannes
pyohannes committed Jan 15, 2024
1 parent e37eac7 commit b4d0c98
Show file tree
Hide file tree
Showing 2 changed files with 109 additions and 41 deletions.
120 changes: 79 additions & 41 deletions docs/attributes-registry/messaging.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,19 @@

# Messaging

## Messaging Attributes
<!-- toc -->

<!-- semconv registry.messaging(omit_requirement_level) -->
- [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)

<!-- tocstop -->

## Generic Messaging Attributes

<!-- semconv registry.messaging(omit_requirement_level,tag=messaging-generic) -->
| 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` |
Expand All @@ -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.
Expand All @@ -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.

Expand All @@ -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 |
<!-- endsemconv -->

## GCP Pub/Sub Attributes

<!-- semconv registry.messaging(omit_requirement_level,tag=tech-specific-gcp-pubsub) -->
| 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` |
<!-- endsemconv -->

## Kafka Attributes

<!-- semconv registry.messaging(omit_requirement_level,tag=tech-specific-kafka) -->
| 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.
<!-- endsemconv -->

## RabbitMQ Attributes

<!-- semconv registry.messaging(omit_requirement_level,tag=tech-specific-rabbitmq) -->
| Attribute | Type | Description | Examples |
|---|---|---|---|
| `messaging.rabbitmq.destination.routing_key` | string | RabbitMQ message routing key. | `myKey` |
<!-- endsemconv -->

## RocketMQ Attributes

<!-- semconv registry.messaging(omit_requirement_level,tag=tech-specific-rocketmq) -->
| 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 |
Expand All @@ -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 |
<!-- endsemconv -->
30 changes: 30 additions & 0 deletions model/registry/messaging.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,18 +12,21 @@ 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'
note: |
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
Expand All @@ -34,33 +37,40 @@ 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'
note: |
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: >
Expand All @@ -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: >
Expand All @@ -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: >
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -243,3 +272,4 @@ groups:
- id: rocketmq
value: 'rocketmq'
brief: 'Apache RocketMQ'
tag: messaging-generic

0 comments on commit b4d0c98

Please sign in to comment.