open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Moved `messaging.*` attributes to the registry (#444) 

Signed-off-by: Alexander Wert <alexander.wert@elastic.co>
This commit is contained in:
Alexander Wert 2023-11-02 17:18:27 +01:00 committed by GitHub
parent c34ca409ad
commit d6a478d8dc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 390 additions and 231 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
docs/attributes-registry/messaging.md Normal file
View File

@ -0,0 +1,85 @@
<!--- Hugo front matter used to generate the website version of this page:
--->
# Messaging
## Messaging Attributes
<!-- semconv registry.messaging(omit_requirement_level) -->
| 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` |
| `messaging.client_id` | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` |
| `messaging.destination.anonymous` | boolean | A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name). | |
| `messaging.destination.name` | string | The message destination name [2] | `MyQueue`; `MyTopic` |
| `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [3] | `/customers/{customerId}` |
| `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.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.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.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.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` |
**[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.
**[2]:** 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.
**[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]:** 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
body size should be used.
**[7]:** 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.
`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.
| Value | Description |
|---|---|
| `publish` | One or more messages are provided for publishing to an intermediary. If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created. |
| `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. |
| `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.rocketmq.consumption_model` MUST be one of the following:
| Value | Description |
|---|---|
| `clustering` | Clustering consumption model |
| `broadcasting` | Broadcasting consumption model |
`messaging.rocketmq.message.type` MUST be one of the following:
| Value | Description |
|---|---|
| `normal` | Normal message |
| `fifo` | FIFO message |
| `delay` | Delay message |
| `transaction` | Transaction message |
<!-- endsemconv -->

12
docs/messaging/kafka.md
View File

@ -24,14 +24,14 @@ described on this page.
For Apache Kafka, the following additional attributes are defined:
<!-- semconv messaging.kafka -->
<!-- semconv messaging.kafka(full,tag=tech-specific-kafka) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `messaging.kafka.consumer.group` | string | Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. | `my-group` | Recommended |
| `messaging.kafka.destination.partition` | int | Partition the message is sent to. | `2` | Recommended |
| `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` | Recommended |
| `messaging.kafka.message.offset` | int | The offset of a record in the corresponding Kafka partition. | `42` | Recommended |
| `messaging.kafka.message.tombstone` | boolean | A boolean that is true if the message is a tombstone. | | Conditionally Required: [2] |
| [`messaging.kafka.consumer.group`](../attributes-registry/messaging.md) | string | Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. | `my-group` | Recommended |
| [`messaging.kafka.destination.partition`](../attributes-registry/messaging.md) | int | Partition the message is sent to. | `2` | Recommended |
| [`messaging.kafka.message.key`](../attributes-registry/messaging.md) | 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` | Recommended |
| [`messaging.kafka.message.offset`](../attributes-registry/messaging.md) | int | The offset of a record in the corresponding Kafka partition. | `42` | Recommended |
| [`messaging.kafka.message.tombstone`](../attributes-registry/messaging.md) | boolean | A boolean that is true if the message is a tombstone. | | Conditionally Required: [2] |
**[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.

53
docs/messaging/messaging-spans.md
View File

@ -273,21 +273,21 @@ messages were received). For each message it accounts for, the "Deliver" or
## Messaging attributes
<!-- semconv messaging -->
<!-- semconv messaging(full) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `messaging.batch.message_count` | int | The number of messages sent, received, or processed in the scope of the batching operation. [1] | `0`; `1`; `2` | Conditionally Required: [2] |
| `messaging.client_id` | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | Recommended: If a client id is available |
| `messaging.destination.anonymous` | boolean | A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name). | | Conditionally Required: [3] |
| `messaging.destination.name` | string | The message destination name [4] | `MyQueue`; `MyTopic` | Conditionally Required: [5] |
| `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [6] | `/customers/{customerId}` | Conditionally Required: [7] |
| `messaging.destination.temporary` | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | Conditionally Required: [8] |
| `messaging.message.body.size` | int | The size of the message body in bytes. [9] | `1439` | Recommended: [10] |
| `messaging.message.conversation_id` | string | The [conversation ID](#conversations) identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | Recommended: [11] |
| `messaging.message.envelope.size` | int | The size of the message body and metadata in bytes. [12] | `2738` | Recommended: [13] |
| `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [14] |
| `messaging.operation` | string | A string identifying the kind of messaging operation as defined in the [Operation names](#operation-names) section above. [15] | `publish` | Required |
| `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Required |
| [`messaging.batch.message_count`](../attributes-registry/messaging.md) | int | The number of messages sent, received, or processed in the scope of the batching operation. [1] | `0`; `1`; `2` | Conditionally Required: [2] |
| [`messaging.client_id`](../attributes-registry/messaging.md) | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | Recommended: If a client id is available |
| [`messaging.destination.anonymous`](../attributes-registry/messaging.md) | boolean | A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name). | | Conditionally Required: [3] |
| [`messaging.destination.name`](../attributes-registry/messaging.md) | string | The message destination name [4] | `MyQueue`; `MyTopic` | Conditionally Required: [5] |
| [`messaging.destination.template`](../attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [6] | `/customers/{customerId}` | Conditionally Required: [7] |
| [`messaging.destination.temporary`](../attributes-registry/messaging.md) | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | Conditionally Required: [8] |
| [`messaging.message.body.size`](../attributes-registry/messaging.md) | int | The size of the message body in bytes. [9] | `1439` | Recommended: [10] |
| [`messaging.message.conversation_id`](../attributes-registry/messaging.md) | string | The conversation ID identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | Recommended: [11] |
| [`messaging.message.envelope.size`](../attributes-registry/messaging.md) | int | The size of the message body and metadata in bytes. [12] | `2738` | Recommended: [13] |
| [`messaging.message.id`](../attributes-registry/messaging.md) | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [14] |
| [`messaging.operation`](../attributes-registry/messaging.md) | string | A string identifying the kind of messaging operation. [15] | `publish` | Required |
| [`messaging.system`](../attributes-registry/messaging.md) | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Required |
| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended |
| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. |
| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [16] | `amqp`; `mqtt` | Recommended |
@ -347,9 +347,26 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
| Value | Description |
|---|---|
| `publish` | publish |
| `receive` | receive |
| `process` | process |
| `publish` | One or more messages are provided for publishing to an intermediary. If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created. |
| `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. |
| `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. |
`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. |
| `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 |
<!-- endsemconv -->
Additionally `server.port` from the [network attributes][] is recommended.
@ -387,8 +404,8 @@ under the namespace `messaging.destination_publish.*`
<!-- semconv messaging.destination_publish -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `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). | | Recommended |
| `messaging.destination_publish.name` | string | The name of the original destination the message was published to [1] | `MyQueue`; `MyTopic` | Recommended |
| [`messaging.destination_publish.anonymous`](../attributes-registry/messaging.md) | boolean | A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name). | | Recommended |
| [`messaging.destination_publish.name`](../attributes-registry/messaging.md) | string | The name of the original destination the message was published to [1] | `MyQueue`; `MyTopic` | Recommended |
**[1]:** 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.

4
docs/messaging/rabbitmq.md
View File

@ -17,10 +17,10 @@ described on this page.
In RabbitMQ, the destination is defined by an *exchange* and a *routing key*.
`messaging.destination.name` MUST be set to the name of the exchange. This will be an empty string if the default exchange is used.
<!-- semconv messaging.rabbitmq -->
<!-- semconv messaging.rabbitmq(full,tag=tech-specific-rabbitmq) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `messaging.rabbitmq.destination.routing_key` | string | RabbitMQ message routing key. | `myKey` | Conditionally Required: If not empty. |
| [`messaging.rabbitmq.destination.routing_key`](../attributes-registry/messaging.md) | string | RabbitMQ message routing key. | `myKey` | Conditionally Required: If not empty. |
<!-- endsemconv -->
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md

20
docs/messaging/rocketmq.md
View File

@ -16,18 +16,18 @@ described on this page.
Specific attributes for Apache RocketMQ are defined below.
<!-- semconv messaging.rocketmq -->
<!-- semconv messaging.rocketmq(full,tag=tech-specific-rocketmq) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `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` | Required |
| `messaging.rocketmq.consumption_model` | string | Model of message consumption. This only applies to consumer spans. | `clustering` | Recommended |
| `messaging.rocketmq.message.delay_time_level` | int | The delay time level for delay message, which determines the message delay time. | `3` | Conditionally Required: [1] |
| `messaging.rocketmq.message.delivery_timestamp` | int | The timestamp in milliseconds that the delay message is expected to be delivered to consumer. | `1665987217045` | Conditionally Required: [2] |
| `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` | Conditionally Required: If the message type is FIFO. |
| `messaging.rocketmq.message.keys` | string[] | Key(s) of message, another way to mark message besides message id. | `[keyA, keyB]` | Recommended |
| `messaging.rocketmq.message.tag` | string | The secondary classifier of message besides topic. | `tagA` | Recommended |
| `messaging.rocketmq.message.type` | string | Type of message. | `normal` | Recommended |
| `messaging.rocketmq.namespace` | string | Namespace of RocketMQ resources, resources in different namespaces are individual. | `myNamespace` | Required |
| [`messaging.rocketmq.client_group`](../attributes-registry/messaging.md) | string | Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. | `myConsumerGroup` | Required |
| [`messaging.rocketmq.consumption_model`](../attributes-registry/messaging.md) | string | Model of message consumption. This only applies to consumer spans. | `clustering` | Recommended |
| [`messaging.rocketmq.message.delay_time_level`](../attributes-registry/messaging.md) | int | The delay time level for delay message, which determines the message delay time. | `3` | Conditionally Required: [1] |
| [`messaging.rocketmq.message.delivery_timestamp`](../attributes-registry/messaging.md) | int | The timestamp in milliseconds that the delay message is expected to be delivered to consumer. | `1665987217045` | Conditionally Required: [2] |
| [`messaging.rocketmq.message.group`](../attributes-registry/messaging.md) | 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` | Conditionally Required: If the message type is FIFO. |
| [`messaging.rocketmq.message.keys`](../attributes-registry/messaging.md) | string[] | Key(s) of message, another way to mark message besides message id. | `[keyA, keyB]` | Recommended |
| [`messaging.rocketmq.message.tag`](../attributes-registry/messaging.md) | string | The secondary classifier of message besides topic. | `tagA` | Recommended |
| [`messaging.rocketmq.message.type`](../attributes-registry/messaging.md) | string | Type of message. | `normal` | Recommended |
| [`messaging.rocketmq.namespace`](../attributes-registry/messaging.md) | string | Namespace of RocketMQ resources, resources in different namespaces are individual. | `myNamespace` | Required |
**[1]:** If the message type is delay and delivery timestamp is not specified.

208
model/registry/messaging.yaml Normal file
View File

@ -0,0 +1,208 @@
groups:
- id: registry.messaging
prefix: messaging
type: attribute_group
brief: 'Attributes describing telemetry around messaging systems and messaging activities.'
attributes:
- id: batch.message_count
type: int
brief: The number of messages sent, received, or processed in the scope of the batching operation.
note: >
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.
examples: [0, 1, 2]
- id: client_id
type: string
brief: >
A unique identifier for the client that consumes or produces a message.
examples: ['client-5', 'myhost@8742@s8083jm']
- 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']
- id: destination.template
type: string
brief: Low cardinality representation of the messaging destination name
note: >
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.
examples: ['/customers/{customerId}']
- 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).'
- 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.'
- 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).'
- 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']
- 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'
- id: kafka.destination.partition
type: int
brief: >
Partition the message is sent to.
examples: 2
- id: kafka.message.key
type: string
brief: >
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.
note: >
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'
- id: kafka.message.offset
type: int
brief: >
The offset of a record in the corresponding Kafka partition.
examples: 42
- id: kafka.message.tombstone
type: boolean
brief: 'A boolean that is true if the message is a tombstone.'
- 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'
- id: message.envelope.size
type: int
brief: >
The size of the message body and metadata in bytes.
note: |
This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed
size should be used.
examples: 2738
- 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'
- id: message.body.size
type: int
brief: >
The size of the message body in bytes.
note: |
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
- id: operation
type:
allow_custom_values: true
members:
- id: publish
value: "publish"
brief: >
One or more messages are provided for publishing to an intermediary.
If a single message is published, the context of the "Publish" span can be used as the creation context and no "Create" span needs to be created.
- id: create
value: "create"
brief: >
A message is created.
"Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios.
- id: receive
value: "receive"
brief: >
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.
- id: deliver
value: "deliver"
brief: >
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.
brief: >
A string identifying the kind of messaging operation.
note: If a custom value is used, it MUST be of low cardinality.
- id: rabbitmq.destination.routing_key
type: string
brief: >
RabbitMQ message routing key.
examples: 'myKey'
- 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'
- id: rocketmq.consumption_model
type:
allow_custom_values: false
members:
- id: clustering
value: 'clustering'
brief: 'Clustering consumption model'
- id: broadcasting
value: 'broadcasting'
brief: 'Broadcasting consumption model'
brief: >
Model of message consumption. This only applies to consumer spans.
- id: rocketmq.message.delay_time_level
type: int
brief: >
The delay time level for delay message, which determines the message delay time.
examples: 3
- 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
- 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'
- id: rocketmq.message.keys
type: string[]
brief: >
Key(s) of message, another way to mark message besides message id.
examples: ['keyA', 'keyB']
- id: rocketmq.message.tag
type: string
brief: >
The secondary classifier of message besides topic.
examples: tagA
- id: rocketmq.message.type
type:
allow_custom_values: false
members:
- id: normal
value: 'normal'
brief: "Normal message"
- id: fifo
value: 'fifo'
brief: 'FIFO message'
- id: delay
value: 'delay'
brief: 'Delay message'
- id: transaction
value: 'transaction'
brief: 'Transaction message'
brief: >
Type of message.
- id: rocketmq.namespace
type: string
brief: >
Namespace of RocketMQ resources, resources in different namespaces are individual.
examples: 'myNamespace'
- id: system
type: string
brief: 'A string identifying the messaging system.'
examples: ['kafka', 'rabbitmq', 'rocketmq', 'activemq', 'AmazonSQS']

239
model/trace/messaging.yaml
View File

@ -1,39 +1,15 @@
groups:
- id: messaging.message
prefix: messaging
type: attribute_group
brief: 'Semantic convention describing per-message attributes populated on messaging spans or links.'
attributes:
- ref: messaging.destination.name
- 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'
- id: message.conversation_id
type: string
brief: >
The [conversation ID](#conversations) identifying the conversation to which the message belongs,
represented as a string. Sometimes called "Correlation ID".
examples: 'MyConversationId'
- id: message.envelope.size
type: int
brief: >
The size of the message body and metadata in bytes.
note: |
This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed
size should be used.
examples: 2738
- id: message.body.size
type: int
brief: >
The size of the message body in bytes.
note: |
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
- ref: messaging.message.id
- ref: messaging.message.conversation_id
- ref: messaging.message.envelope.size
- ref: messaging.message.body.size
- id: messaging.destination
prefix: messaging.destination
type: attribute_group
brief: 'Semantic convention for attributes that describe messaging destination on broker'
note: |
@ -46,29 +22,10 @@ groups:
applies to all messages in the batch.
In other cases, destination attributes may be set on links.
attributes:
- id: 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']
- id: template
type: string
brief: Low cardinality representation of the messaging destination name
note: >
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.
examples: ['/customers/{customerId}']
- id: temporary
type: boolean
brief: 'A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed.'
- id: anonymous
type: boolean
brief: 'A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name).'
- ref: messaging.destination.name
- ref: messaging.destination.template
- ref: messaging.destination.temporary
- ref: messaging.destination.anonymous
- id: messaging.destination_publish
prefix: messaging.destination_publish
@ -87,61 +44,25 @@ groups:
applies to all messages in the batch.
In other cases, destination attributes may be set on links.
attributes:
- id: 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']
- id: anonymous
type: boolean
brief: 'A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name).'
- ref: messaging.destination_publish.name
- ref: messaging.destination_publish.anonymous
- id: messaging
prefix: messaging
type: span
brief: >
This document defines general attributes used in
messaging systems.
attributes:
- id: system
type: string
- ref: messaging.system
requirement_level: required
brief: 'A string identifying the messaging system.'
examples: ['kafka', 'rabbitmq', 'rocketmq', 'activemq', 'AmazonSQS']
- id: operation
type:
allow_custom_values: true
members:
- id: publish
value: "publish"
- id: receive
value: "receive"
- id: process
value: "process"
- ref: messaging.operation
requirement_level: required
brief: >
A string identifying the kind of messaging operation as defined in the
[Operation names](#operation-names) section above.
note: If a custom value is used, it MUST be of low cardinality.
- id: batch.message_count
type: int
brief: The number of messages sent, received, or processed in the scope of the batching operation.
- ref: messaging.batch.message_count
requirement_level:
conditionally_required: If the span describes an operation on a batch of messages.
note: >
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.
examples: [0, 1, 2]
- id: client_id
type: string
- ref: messaging.client_id
requirement_level:
recommended: If a client id is available
brief: >
A unique identifier for the client that consumes or produces a message.
examples: ['client-5', 'myhost@8742@s8083jm']
- ref: messaging.destination.name
requirement_level:
conditionally_required: If span describes operation on a single message or if the value applies to all messages in the batch.
@ -188,136 +109,64 @@ groups:
- ref: network.protocol.version
- id: messaging.rabbitmq
prefix: messaging.rabbitmq
type: attribute_group
extends: messaging
brief: >
Attributes for RabbitMQ
attributes:
- id: destination.routing_key
type: string
- ref: messaging.rabbitmq.destination.routing_key
requirement_level:
conditionally_required: If not empty.
brief: >
RabbitMQ message routing key.
examples: 'myKey'
tag: tech-specific-rabbitmq
- id: messaging.kafka
prefix: messaging.kafka
type: attribute_group
extends: messaging
brief: >
Attributes for Apache Kafka
attributes:
- id: message.key
type: string
brief: >
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.
note: >
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'
- id: 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'
- id: destination.partition
type: int
brief: >
Partition the message is sent to.
examples: 2
- id: message.offset
type: int
brief: >
The offset of a record in the corresponding Kafka partition.
examples: 42
- id: message.tombstone
type: boolean
- ref: messaging.kafka.message.key
tag: tech-specific-kafka
- ref: messaging.kafka.consumer.group
tag: tech-specific-kafka
- ref: messaging.kafka.destination.partition
tag: tech-specific-kafka
- ref: messaging.kafka.message.offset
tag: tech-specific-kafka
- ref: messaging.kafka.message.tombstone
requirement_level:
conditionally_required: If value is `true`. When missing, the value is assumed to be `false`.
brief: 'A boolean that is true if the message is a tombstone.'
tag: tech-specific-kafka
- id: messaging.rocketmq
prefix: messaging.rocketmq
type: attribute_group
extends: messaging
brief: >
Attributes for Apache RocketMQ
attributes:
- id: namespace
type: string
- ref: messaging.rocketmq.namespace
requirement_level: required
brief: >
Namespace of RocketMQ resources, resources in different namespaces are individual.
examples: 'myNamespace'
- id: client_group
type: string
tag: tech-specific-rocketmq
- ref: messaging.rocketmq.client_group
requirement_level: required
brief: >
Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind.
examples: 'myConsumerGroup'
- id: message.delivery_timestamp
type: int
tag: tech-specific-rocketmq
- ref: messaging.rocketmq.message.delivery_timestamp
requirement_level:
conditionally_required: If the message type is delay and delay time level is not specified.
brief: >
The timestamp in milliseconds that the delay message is expected to be delivered to consumer.
examples: 1665987217045
- id: message.delay_time_level
type: int
tag: tech-specific-rocketmq
- ref: messaging.rocketmq.message.delay_time_level
requirement_level:
conditionally_required: If the message type is delay and delivery timestamp is not specified.
brief: >
The delay time level for delay message, which determines the message delay time.
examples: 3
- id: message.group
type: string
tag: tech-specific-rocketmq
- ref: messaging.rocketmq.message.group
requirement_level:
conditionally_required: If the message type is FIFO.
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'
- id: message.type
type:
allow_custom_values: false
members:
- id: normal
value: 'normal'
brief: "Normal message"
- id: fifo
value: 'fifo'
brief: 'FIFO message'
- id: delay
value: 'delay'
brief: 'Delay message'
- id: transaction
value: 'transaction'
brief: 'Transaction message'
brief: >
Type of message.
- id: message.tag
type: string
brief: >
The secondary classifier of message besides topic.
examples: tagA
- id: message.keys
type: string[]
brief: >
Key(s) of message, another way to mark message besides message id.
examples: ['keyA', 'keyB']
- id: consumption_model
type:
allow_custom_values: false
members:
- id: clustering
value: 'clustering'
brief: 'Clustering consumption model'
- id: broadcasting
value: 'broadcasting'
brief: 'Broadcasting consumption model'
brief: >
Model of message consumption. This only applies to consumer spans.
tag: tech-specific-rocketmq
- ref: messaging.rocketmq.message.type
tag: tech-specific-rocketmq
- ref: messaging.rocketmq.message.tag
tag: tech-specific-rocketmq
- ref: messaging.rocketmq.message.keys
tag: tech-specific-rocketmq
- ref: messaging.rocketmq.consumption_model
tag: tech-specific-rocketmq