clarify destination attributes on consumers

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`,

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

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:

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 `<operation name>` 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.
 
 <!-- semconv messaging.producer -->
 | 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.
 
 <!-- semconv messaging.consumer -->
 | 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*.
 <!-- semconv messaging.rabbitmq -->
 | 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. |
 <!-- endsemconv -->
 
 #### 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.