From 8dfd92ca9ed9feba0031761c8ae3b8db37bc010b Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Mon, 7 Aug 2023 18:58:19 +0200 Subject: [PATCH] Re-introduce namespace to describe the original destination (#156) Co-authored-by: Armin Ruech --- CHANGELOG.md | 3 +++ docs/messaging/messaging-spans.md | 30 +++++++++++++++++++++++++++--- model/trace/messaging.yaml | 28 ++++++++++++++++++++++++++++ 3 files changed, 58 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 10ee6bcda1..2009f95066 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index cee92e4815..a8a642acff 100644 --- a/docs/messaging/messaging-spans.md +++ b/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.*` + + +| 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. + + 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. diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index 5df3c54698..bb7a768638 100644 --- a/model/trace/messaging.yaml +++ b/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