From 57ec5e8551707b4c181cac477df597df134c1368 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 21 Nov 2022 14:32:27 -0800 Subject: [PATCH] clarify destination attributes on consumers --- CHANGELOG.md | 4 +-- schemas/1.16.0 | 4 +-- semantic_conventions/trace/messaging.yaml | 23 +++++++++++++-- .../trace/semantic_conventions/messaging.md | 29 +++++++++++++------ 4 files changed, 44 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 84472f7ac16..a2a33eba7ad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -57,9 +57,9 @@ release. `messaging.conversation_id` to `messaging.message.conversation_id`, `messaging.message_payload_size_bytes` to `messaging.message.payload_size_bytes`, `messaging.message_payload_compressed_size_bytes` to `messaging.message.payload_compressed_size_bytes`, - `messaging.rabbitmq.routing_key`: `messaging.rabbitmq.message.routing_key`, + `messaging.rabbitmq.routing_key`: `messaging.rabbitmq.destination.routing_key`, `messaging.kafka.message_key` to `messaging.kafka.message.key`, - `messaging.kafka.partition` to `messaging.kafka.message.partition`, + `messaging.kafka.partition` to `messaging.kafka.destination.partition`, `messaging.kafka.tombstone` to `messaging.kafka.message.tombstone`, `messaging.rocketmq.message_type` to `messaging.rocketmq.message.type`, `messaging.rocketmq.message_tag` to `messaging.rocketmq.message.tag`, diff --git a/schemas/1.16.0 b/schemas/1.16.0 index f5339c558ea..06fdad6e753 100644 --- a/schemas/1.16.0 +++ b/schemas/1.16.0 @@ -16,9 +16,9 @@ versions: messaging.conversation_id: messaging.message.conversation_id messaging.message_payload_size_bytes: messaging.message.payload_size_bytes messaging.message_payload_compressed_size_bytes: messaging.message.payload_compressed_size_bytes - messaging.rabbitmq.routing_key: messaging.rabbitmq.message.routing_key + messaging.rabbitmq.routing_key: messaging.rabbitmq.destination.routing_key messaging.kafka.message_key: messaging.kafka.message.key - messaging.kafka.partition: messaging.kafka.message.partition + messaging.kafka.partition: messaging.kafka.destination.partition messaging.kafka.tombstone: messaging.kafka.message.tombstone messaging.rocketmq.message_type: messaging.rocketmq.message.type messaging.rocketmq.message_tag: messaging.rocketmq.message.tag diff --git a/semantic_conventions/trace/messaging.yaml b/semantic_conventions/trace/messaging.yaml index 0c1b10805df..cbf40795b1b 100644 --- a/semantic_conventions/trace/messaging.yaml +++ b/semantic_conventions/trace/messaging.yaml @@ -66,7 +66,7 @@ groups: brief: > A string identifying the kind of messaging operation as defined in the [Operation names](#operation-names) section above. - note: If custom value is used, it MUST known to be of low cardinality. + note: If a custom value is used, it MUST known to be of low cardinality. - id: batch.size type: int brief: The number of messages sent, received, or processed in the scope of the batching operation. @@ -221,6 +221,18 @@ groups: requirement_level: recommended: when supported by messaging system and only if the source is anonymous. If missing, assumed to be false. brief: 'A boolean that is true if the message source is anonymous (could be unnamed or have auto-generated name).' + - ref: messaging.destination.name + requirement_level: + recommended: If known on consumer + - ref: messaging.destination.kind + requirement_level: + recommended: If known on consumer + - ref: messaging.destination.temporary + requirement_level: + recommended: If known on consumer + - ref: messaging.destination.anonymous + requirement_level: + recommended: If known on consumer - id: messaging.consumer.synchronous prefix: messaging @@ -238,7 +250,7 @@ groups: brief: > Attributes for RabbitMQ attributes: - - id: message.routing_key + - id: destination.routing_key type: string requirement_level: conditionally_required: If not empty. @@ -274,11 +286,16 @@ groups: brief: > Client Id for the Consumer or Producer that is handling the message. examples: 'client-5' - - id: message.partition + - id: destination.partition type: int brief: > Partition the message is sent to. examples: 2 + - id: source.partition + type: int + brief: > + Partition the message is received from. + examples: 2 - id: message.tombstone type: boolean requirement_level: diff --git a/specification/trace/semantic_conventions/messaging.md b/specification/trace/semantic_conventions/messaging.md index 4cde00b5709..da7f9d6cf8a 100644 --- a/specification/trace/semantic_conventions/messaging.md +++ b/specification/trace/semantic_conventions/messaging.md @@ -155,7 +155,7 @@ The destination name SHOULD only be used for the span name if it is known to be This can be assumed if it is statically derived from application code or configuration. Wherever possible, the real destination names after resolving logical or aliased names SHOULD be used. If the destination name is dynamic, such as a [conversation ID](#conversations) or a value obtained from a `Reply-To` header, it SHOULD NOT be used for the span name. -In these cases, an artificial destination name that best expresses the destination, or a generic, static fallback like `"(anonymous)"` for [anonymous destinations](#temporary-and-anonymous-destinations) SHOULD be used instead.anonymous +In these cases, an artificial destination name that best expresses the destination, or a generic, static fallback like `"(anonymous)"` for [anonymous destinations](#temporary-and-anonymous-destinations) SHOULD be used instead. The values allowed for `` are defined in the section [Operation names](#operation-names) below. If the format above is used, the operation name MUST match the `messaging.operation` attribute defined for message consumer spans below. @@ -206,7 +206,7 @@ The following operations related to messages are defined for these semantic conv | [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [11] | | [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [12] | -**[1]:** If custom value is used, it MUST known to be of low cardinality. +**[1]:** If a custom value is used, it MUST known to be of low cardinality. **[2]:** Instrumentations SHOULD NOT set `messaging.batch.size` on spans that operate with a single message. When client library supports batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.size` for batching APIs and SHOULD NOT use it for single-message APIs. @@ -253,7 +253,7 @@ logical entity messages are received from. Attributes in `messaging.batch` names ### Producer attributes -Following additional attributes describe message producer operations. +The following additional attributes describe message producer operations. | Attribute | Type | Description | Examples | Requirement Level | @@ -289,7 +289,7 @@ broker does not have such notion, destination name SHOULD uniquely identify brok ### Consumer attributes -Following additional attributes describe message consumer operations. +The following additional attributes describe message consumer operations. | Attribute | Type | Description | Examples | Requirement Level | @@ -299,7 +299,11 @@ Following additional attributes describe message consumer operations. | `messaging.source.template` | string | Low cardinality field representing messaging source [2] | `/customers/{customerId}` | Conditionally Required: [3] | | `messaging.source.temporary` | boolean | A boolean that is true if the message source is temporary and might not exist anymore after messages are processed. | | Recommended: [4] | | `messaging.source.anonymous` | boolean | A boolean that is true if the message source is anonymous (could be unnamed or have auto-generated name). | | Recommended: [5] | -| `messaging.source.name` | string | The message source name [6] | `MyQueue`; `MyTopic` | Conditionally Required: [7] | +| `messaging.destination.anonymous` | boolean | A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name). | | Recommended: If known on consumer | +| `messaging.destination.kind` | string | The kind of message destination | `queue` | Recommended: If known on consumer | +| `messaging.destination.name` | string | The message destination name [6] | `MyQueue`; `MyTopic` | Recommended: If known on consumer | +| `messaging.destination.temporary` | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | Recommended: If known on consumer | +| `messaging.source.name` | string | The message source name [7] | `MyQueue`; `MyTopic` | Conditionally Required: [8] | **[1]:** If the message source is either a `queue` or `topic`. @@ -311,10 +315,13 @@ Following additional attributes describe message consumer operations. **[5]:** when supported by messaging system and only if the source is anonymous. If missing, assumed to be false. -**[6]:** Source name SHOULD uniquely identify specific queue, topic, or other entity within broker. If +**[6]:** Destination name SHOULD uniquely identify specific queue, topic, or other entity within broker. If +broker does not have such notion, destination name SHOULD uniquely identify broker. + +**[7]:** Source name SHOULD uniquely identify specific queue, topic, or other entity within broker. If broker does not have such notion, source name SHOULD uniquely identify broker. -**[7]:** If the value applies to all messages in the batch. +**[8]:** If the value applies to all messages in the batch. `messaging.source.kind` 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. @@ -331,6 +338,9 @@ For batch receiving and processing (see the [Batch receiving](#batch-receiving) Even though in that case one might think that the processing span's kind should be `INTERNAL`, that kind MUST NOT be used. Instead span kind should be set to either `CONSUMER` or `SERVER` according to the rules defined above. + +> Note: Consumer spans can have attributes describing source and destination. Since messages could be routed by brokers, source and destination don't always match. If original destination information is available on the consumer, consumer instrumentations SHOULD populate corresponding `messaging.destination` attributes. + ### Per-message attributes All messaging operations (`publish`, `receive`, `process`, or other not covered by this specification) can describe a batch of messages. @@ -358,7 +368,7 @@ In RabbitMQ, the destination is defined by an *exchange* and a *routing key*. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `messaging.rabbitmq.message.routing_key` | string | RabbitMQ message routing key. | `myKey` | Conditionally Required: If not empty. | +| `messaging.rabbitmq.destination.routing_key` | string | RabbitMQ message routing key. | `myKey` | Conditionally Required: If not empty. | #### Apache Kafka @@ -371,7 +381,8 @@ For Apache Kafka, the following additional attributes are defined: | `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.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.client_id` | string | Client Id for the Consumer or Producer that is handling the message. | `client-5` | Recommended | -| `messaging.kafka.message.partition` | int | Partition the message is sent to. | `2` | Recommended | +| `messaging.kafka.destination.partition` | int | Partition the message is sent to. | `2` | Recommended | +| `messaging.kafka.source.partition` | int | Partition the message is received from. | `2` | Recommended | | `messaging.kafka.message.tombstone` | 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.