Re-introduce namespace to describe the original destination (open-tel…

…emetry#156)

Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com>

CHANGELOG.md

@@ -17,6 +17,9 @@ release.
   ([#224](https://github.com/open-telemetry/semantic-conventions/pull/224))
 - Update HTTP `network.protocol.version` examples to match HTTP RFCs.
   ([#228](https://github.com/open-telemetry/semantic-conventions/pull/228))
+- Re-introduce namespace and attributes to describe the original destination messages were
+  published to (`messaging.destination_publish.*`).
+  ([#156](https://github.com/open-telemetry/semantic-conventions/pull/156))
 - Generate FaaS metric semantic conventions from YAML.
   ([#88](https://github.com/open-telemetry/semantic-conventions/pull/88))
   The conventions cover metrics that are recorded by the FaaS itself and not by

docs/messaging/messaging-spans.md

@@ -105,6 +105,12 @@ A destination is usually uniquely identified by its name within
 the messaging system instance.
 Examples of a destination name would be an URL or a simple one-word identifier.
 
+In some use cases, messages are routed within one or multiple brokers. In such
+cases, the destination the message was originally published to is different
+from the destination it is being consumed from. When information about the
+destination where the message was originally published to is available, consumers
+can record them under the `destination_publish` namespace.
+
 Typical examples of destinations include Kafka topics, RabbitMQ queues and topics.
 
 ### Message consumption
@@ -281,9 +287,8 @@ These attributes should be set to the broker to which the message is sent/from w
 ### Attribute namespaces
 
 - `messaging.message`: Contains attributes that describe individual messages
-- `messaging.destination`: Contains attributes that describe the logical entity
-   messages are published to and received from.
-   See [Destinations](#destinations) for more details
+- `messaging.destination`: Contains attributes that describe the logical entity messages are published to. See [Destinations](#destinations) for more details
+- `messaging.destination_publish`: Contains attributes that describe the logical entity messages were originally published to. See [Destinations](#destinations) for more details
 - `messaging.batch`: Contains attributes that describe batch operations
 - `messaging.consumer`: Contains attributes that describe application instance that consumes a message. See [consumer](#consumer) for more details
 
@@ -298,6 +303,25 @@ as described in [Attributes specific to certain messaging systems](#attributes-s
 
 ### Consumer attributes
 
+The following additional attributes describe message consumer operations.
+
+Since messages could be routed by brokers, the destination messages are published
+to may not match with the destination they are consumed from.
+
+If information about the original destination is available on the consumer,
+consumer instrumentations SHOULD populate the attributes
+under the namespace `messaging.destination_publish.*`
+
+<!-- semconv messaging.destination_publish -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `messaging.destination_publish.name` | string | The name of the original destination the message was published to [1] | `MyQueue`; `MyTopic` | Recommended |
+| `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 |
+
+**[1]:** The name SHOULD uniquely identify a specific queue, topic, or other entity within the broker. If
+the broker does not have such notion, the original destination name SHOULD uniquely identify the broker.
+<!-- endsemconv -->
+
 The *receive* span is used to track the time used for receiving the message(s), whereas the *process* span(s) track the time for processing the message(s).
 Note that one or multiple Spans with `messaging.operation` = `process` may often be the children of a Span with `messaging.operation` = `receive`.
 The distinction between receiving and processing of messages is not always of particular interest or sometimes hidden away in a framework (see the [Message consumption](#message-consumption) section above) and therefore the attribute can be left out.

model/trace/messaging.yaml

@@ -64,6 +64,34 @@ groups:
         type: boolean
         brief: 'A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name).'
 
+  - id: messaging.destination_publish
+    prefix: messaging.destination_publish
+    type: attribute_group
+    brief: >
+      Semantic convention for attributes that describe the publish messaging destination on broker.
+      The term Publish Destination refers to the destination the message was originally published to.
+      These attributes should be used on the consumer side when information about
+      the publish destination is available and different than the destination message are consumed from.
+    note: |
+      Publish destination attributes should be set on publish, receive,
+      or other spans describing messaging operations.
+      Destination attributes should be set when the messaging operation handles
+      single messages. When the operation handles a batch of messages,
+      the destination attributes should only be applied when the attribute value
+      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 does not 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).'
+
   - id: messaging
     prefix: messaging
     type: span