BREAKING: Rename messaging.operation to messaging.operation.name (#…

…913) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
open-telemetry · Apr 16, 2024 · f12a4d3 · f12a4d3
1 parent 677ab9e
commit f12a4d3
Show file tree

Hide file tree

Showing 10 changed files with 65 additions and 48 deletions.
diff --git a/.chloggen/890.yaml b/.chloggen/890.yaml
@@ -0,0 +1,4 @@
+change_type: breaking
+component: messaging
+note: Rename `messaging.operation` to `messaging.operation.type`, add `messaging.operation.name`.
+issues: [ 890 ]
diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md
@@ -34,7 +34,8 @@
 | `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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `messaging.message.envelope.size` | int | The size of the message body and metadata in bytes. [6] | `2738` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `messaging.operation` | string | A string identifying the kind of messaging operation. [7] | `publish` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `messaging.operation.name` | string | The system-specific name of the messaging operation. | `ack`; `nack`; `send` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `messaging.operation.type` | string | A string identifying the type of the messaging operation. [7] | `publish` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `messaging.system` | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `activemq` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 **[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.
@@ -55,7 +56,7 @@ size should be used.
 
 **[7]:** 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.
+`messaging.operation.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 | Stability |
 |---|---|---|
@@ -177,5 +178,6 @@ size should be used.
 <!-- semconv registry.messaging.deprecated(omit_requirement_level) -->
 | Attribute  | Type | Description  | Examples  | Stability |
 |---|---|---|---|---|
-| `messaging.kafka.destination.partition` | int | "Deprecated, use `messaging.destination.partition.id` instead." | `2` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.destination.partition.id`. |
+| `messaging.kafka.destination.partition` | int | Deprecated, use `messaging.destination.partition.id` instead. | `2` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.destination.partition.id`. |
+| `messaging.operation` | string | Deprecated, use `messaging.operation.type` instead. | `publish`; `create`; `process` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.operation.type`. |
 <!-- endsemconv -->
diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md
@@ -12,15 +12,6 @@ The Semantic Conventions for [Azure Service Bus](https://learn.microsoft.com/azu
 
 `messaging.system` MUST be set to `"servicebus"`.
 
-### Span names
-
-The span name SHOULD follow [the general messaging span name pattern](../messaging/azure-messaging.md): it SHOULD start with the messaging destination name (Event Hubs queue or topic name) and contain a low-cardinality name of the operation the span describes:
-
-- Spans names for `settle` operations SHOULD follow the `<destination name> {messaging.servicebus.disposition_status}` pattern.
-  For example, `my-queue complete` or `my-queue abandon`.
-- Spans names for `publish` operations SHOULD follow the `<destination name> send` pattern.
-- Spans for `create`, `receive`, and `publish` operations SHOULD follow the general `<destination name> <operation name>` pattern.
-
 ### Span attributes
 
 The following additional attributes are defined:
@@ -39,15 +30,6 @@ The following additional attributes are defined:
 
 `messaging.system` MUST be set to `"eventhubs"`.
 
-### Span names
-
-The span name SHOULD follow the [general messaging span name pattern](../messaging/azure-messaging.md): it SHOULD start with the messaging destination name (Event Hubs namespace) and
-contain a low-cardinality name of an operation the span describes:
-
-- Spans for `settle` operations SHOULD follow the `<destination name> checkpoint` pattern (matching Event Hubs terminology).
-- Spans names for `publish` operations SHOULD follow the `<destination name> send` pattern.
-- Spans for `create`, `receive`, and `publish` operations SHOULD follow the general `<destination name> <operation name>` pattern.
-
 ### Span attributes
 
 The following additional attributes are defined:

diff --git a/docs/messaging/gcp-pubsub.md b/docs/messaging/gcp-pubsub.md
@@ -53,7 +53,7 @@ flowchart LR;
 | Status | `Ok` | `Ok` | `Ok` |
 | `messaging.batch.message_count` |  |  | 2 |
 | `messaging.destination.name` | `"T"` | `"T"` | `"T"` |
-| `messaging.operation` | `"create"` | `"create"` | `"publish"` |
+| `messaging.operation.type` | `"create"` | `"create"` | `"publish"` |
 | `messaging.message.id` | `"a1"` | `"a2"` | |
 | `messaging.message.envelope.size` | `1` | `1` | |
 | `messaging.system` | `"gcp_pubsub"` | `"gcp_pubsub"` | `"gcp_pubsub"` |

diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md
@@ -53,7 +53,7 @@ One process, CA, receives the message and publishes a new message to a topic T2
 
 Frameworks such as Quarkus and Spring Boot separate processing of a received message from producing subsequent messages out.
 For this reason, receiving (Span Rcv1) is the parent of both processing (Span Proc1) and producing a new message (Span Prod2).
-The span representing message receiving (Span Rcv1) should not set `messaging.operation` to `receive`,
+The span representing message receiving (Span Rcv1) should not set `messaging.operation.type` to `receive`,
 as it does not only receive the message but also converts the input message to something suitable for the processing operation to consume and creates the output message from the result of processing.
 
 ```
@@ -77,7 +77,7 @@ Process CB:                           | Span Rcv2 |
 | `service.name` |  | `"myConsumer1"` | `"myConsumer1"` |  | `"myConsumer2"` |
 | `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` |
 | `messaging.destination.name` | `"T1"` | `"T1"` | `"T1"` | `"T2"` | `"T2"` |
-| `messaging.operation` |  |  | `"process"` |  | `"receive"` |
+| `messaging.operation.type` |  |  | `"process"` |  | `"receive"` |
 | `messaging.client_id` |  | `"5"` | `"5"` | `"5"` | `"8"` |
 | `messaging.kafka.message.key` | `"myKey"` | `"myKey"` | `"myKey"` | `"anotherKey"` | `"anotherKey"` |
 | `messaging.kafka.consumer.group` |  | `"my-group"` | `"my-group"` |  | `"another-group"` |

diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md
@@ -18,7 +18,7 @@
 - [Conventions](#conventions)
   - [Context propagation](#context-propagation)
   - [Span name](#span-name)
-  - [Operation names](#operation-names)
+  - [Operation types](#operation-types)
   - [Span kind](#span-kind)
   - [Trace structure](#trace-structure)
     - [Producer spans](#producer-spans)
@@ -153,37 +153,42 @@ in such a way that it cannot be changed by intermediaries.
 
 ### Span name
 
-The span name SHOULD be set to the message destination name and the operation being performed in the following format:
+The span name SHOULD be set to the message destination name and the name of the operation being performed (as captured in [`messaging.operation.name`](../attributes-registry/messaging.md)) in the following format:
 
 ```
 <destination name> <operation name>
 ```
 
+If the operation name is not specified by the messaging system, then the operation type as defined in [Operation types](#operation-types) SHOULD be used:
+
+```
+<destination name> <operation type>
+```
+
 The destination name SHOULD only be used for the span name if it is known to be of low cardinality (cf. [general span name guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/trace/api.md#span)).
 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.
 
-The values allowed for `<operation name>` are defined in the section [Operation names](#operation-names) below.
-
 Examples:
 
 * `shop.orders publish`
-* `shop.orders receive`
+* `shop.orders subscribe`
 * `shop.orders settle`
 * `print_jobs publish`
+* `print_jobs nack`
 * `topic with spaces process`
 * `AuthenticationRequest-Conversations settle`
-* `(anonymous) publish` (`(anonymous)` being a stable identifier for an unnamed destination)
+* `(anonymous) send` (`(anonymous)` being a stable identifier for an unnamed destination)
 
 Messaging system specific adaptions to span naming MUST be documented in [semantic conventions for specific messaging technologies](#semantic-conventions-for-specific-messaging-technologies).
 
-### Operation names
+### Operation types
 
-The following operations related to messages are defined for these semantic conventions:
+The following operation types related to messages are defined for these semantic conventions:
 
-| Operation name | Description |
+| Operation type | Description |
 | -------------- | ----------- |
 | `create`       | A message is created or passed to a client library for publishing. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. |
 | `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. |
@@ -194,9 +199,9 @@ The following operations related to messages are defined for these semantic conv
 ### Span kind
 
 [Span kinds](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/trace/api.md#spankind)
-SHOULD be set according to the following table, based on the operation a span describes.
+SHOULD be set according to the following table, based on the operation type a span describes.
 
-| Operation name | Span kind|
+| Operation type | Span kind|
 |----------------|-------------|
 | `create`       | `PRODUCER` |
 | `publish`      | `PRODUCER` if the context of the "Publish" span is used as creation context. |
@@ -281,7 +286,7 @@ as described in [Attributes specific to certain messaging systems](#attributes-s
 <!-- semconv messaging(full) -->
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-| [`messaging.operation`](../attributes-registry/messaging.md) | string | A string identifying the kind of messaging operation. [1] | `publish` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`messaging.operation.type`](../attributes-registry/messaging.md) | string | A string identifying the type of the messaging operation. [1] | `publish` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | [`messaging.system`](../attributes-registry/messaging.md) | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `activemq` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | [`error.type`](../attributes-registry/error.md) | string | Describes a class of error the operation ended with. [2] | `amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error` | `Conditionally Required` [3] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 | [`messaging.batch.message_count`](../attributes-registry/messaging.md) | int | The number of messages sent, received, or processed in the scope of the batching operation. [4] | `0`; `1`; `2` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
@@ -296,9 +301,10 @@ as described in [Attributes specific to certain messaging systems](#attributes-s
 | [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | [`messaging.message.envelope.size`](../attributes-registry/messaging.md) | int | The size of the message body and metadata in bytes. [14] | `2738` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the messaging intermediary node where the operation was performed. [15] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` If applicable for this messaging system. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`messaging.operation.name`](../attributes-registry/messaging.md) | string | The system-specific name of the messaging operation. | `ack`; `nack`; `send` | `Recommended` [15] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the messaging intermediary node where the operation was performed. [16] | `10.1.2.80`; `/tmp/my.sock` | `Recommended` If applicable for this messaging system. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 | [`network.peer.port`](../attributes-registry/network.md) | int | Peer port of the messaging intermediary node where the operation was performed. | `65123` | `Recommended` if and only if `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
-| [`server.port`](../attributes-registry/server.md) | int | Server port number. [16] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+| [`server.port`](../attributes-registry/server.md) | int | Server port number. [17] | `80`; `8080`; `443` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
 
 **[1]:** If a custom value is used, it MUST be of low cardinality.
 
@@ -345,13 +351,15 @@ body size should be used.
 **[14]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed
 size should be used.
 
-**[15]:** Semantic conventions for individual messaging systems SHOULD document whether `network.peer.*` attributes are applicable.
+**[15]:** If the operation is not sufficiently described by `messaging.operation.type`.
+
+**[16]:** Semantic conventions for individual messaging systems SHOULD document whether `network.peer.*` attributes are applicable.
 Network peer address and port are important when the application interacts with individual intermediary nodes directly,
 If a messaging operation involved multiple network calls (for example retries), the address of the last contacted node SHOULD be used.
 
-**[16]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
+**[17]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
 
-`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.
+`messaging.operation.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 | Stability |
 |---|---|---|
@@ -469,7 +477,7 @@ flowchart LR;
 | `server.port` | `1234` | `1234` | `1234` |
 | `messaging.system` | `"rabbitmq"` | `"rabbitmq"` | `"rabbitmq"` |
 | `messaging.destination.name` | `"T"` | `"T"` | `"T"` |
-| `messaging.operation` | `"publish"` | `"process"` | `"process"` |
+| `messaging.operation.type` | `"publish"` | `"process"` | `"process"` |
 | `messaging.message.id` | `"a"` | `"a"`| `"a"` |
 
 ### Batch receiving
@@ -507,7 +515,7 @@ flowchart LR;
 | `server.port` | `1234` | `1234` | `1234` |
 | `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` |
 | `messaging.destination.name` | `"Q"` | `"Q"` | `"Q"` |
-| `messaging.operation` | `"publish"` | `"publish"` | `"receive"` |
+| `messaging.operation.type` | `"publish"` | `"publish"` | `"receive"` |
 | `messaging.message.id` | `"a1"` | `"a2"` | |
 | `messaging.batch.message_count` |  |  | 2 |
 
@@ -552,7 +560,7 @@ flowchart LR;
 | `server.port` | `1234` | `1234` | `1234` | `1234` | `1234` |
 | `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` |
 | `messaging.destination.name` | `"Q"` | `"Q"` | `"Q"` | `"Q"` | `"Q"` |
-| `messaging.operation` | `"create"` | `"create"` | `"publish"` | `"receive"` | `"receive"` |
+| `messaging.operation.type` | `"create"` | `"create"` | `"publish"` | `"receive"` | `"receive"` |
 | `messaging.message.id` | `"a1"` | `"a2"` | | `"a1"` | `"a2"` |
 | `messaging.batch.message_count` | | | 2 | | |
 

diff --git a/model/registry/deprecated/messaging.yaml b/model/registry/deprecated/messaging.yaml
@@ -6,7 +6,14 @@ groups:
       - id: messaging.kafka.destination.partition
         type: int
         brief: >
-          "Deprecated, use `messaging.destination.partition.id` instead."
+          Deprecated, use `messaging.destination.partition.id` instead.
         examples: 2
         deprecated: "Replaced by `messaging.destination.partition.id`."
         stability: experimental
+      - id: messaging.operation
+        type: string
+        stability: experimental
+        brief: >
+          Deprecated, use `messaging.operation.type` instead.
+        examples: ["publish", "create", "process"]
+        deprecated: "Replaced by `messaging.operation.type`."
diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml
@@ -139,7 +139,7 @@ groups:
           body size should be used.
         examples: 1439
         tag: messaging-generic
-      - id: operation
+      - id: operation.type
         type:
           allow_custom_values: true
           members:
@@ -173,9 +173,16 @@ groups:
               stability: experimental
         stability: experimental
         brief: >
-          A string identifying the kind of messaging operation.
+          A string identifying the type of the messaging operation.
         note: If a custom value is used, it MUST be of low cardinality.
         tag: messaging-generic
+      - id: operation.name
+        type: string
+        stability: experimental
+        brief: >
+          The system-specific name of the messaging operation.
+        examples: [ "ack", "nack", "send" ]
+        tag: messaging-generic
       - id: rabbitmq.destination.routing_key
         type: string
         stability: experimental