PR comments

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.name` | string | A string identifying the name of the 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.name` 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 |
 |---|---|---|
@@ -178,5 +179,5 @@ size should be used.
 | 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.operation` | string | Deprecated, use `messaging.operation.name` instead. | `publish`; `create`; `process` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `messaging.operation.name`. |
+| `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 -->

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:

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.name`](../attributes-registry/messaging.md) | string | A string identifying the name of the 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.name` 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.name` | `"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.name` | `"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.name` | `"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 | | |
 

model/registry/deprecated/messaging.yaml

@@ -14,6 +14,6 @@ groups:
         type: string
         stability: experimental
         brief: >
-          Deprecated, use `messaging.operation.name` instead.
+          Deprecated, use `messaging.operation.type` instead.
         examples: ["publish", "create", "process"]
-        deprecated: "Replaced by `messaging.operation.name`."
+        deprecated: "Replaced by `messaging.operation.type`."

model/registry/messaging.yaml

@@ -139,7 +139,7 @@ groups:
           body size should be used.
         examples: 1439
         tag: messaging-generic
-      - id: operation.name
+      - id: operation.type
         type:
           allow_custom_values: true
           members:
@@ -173,9 +173,16 @@ groups:
               stability: experimental
         stability: experimental
         brief: >
-          A string identifying the name of the 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

model/trace/messaging.yaml

@@ -54,8 +54,11 @@ groups:
         messaging systems.
     extends: messaging.attributes.common
     attributes:
-      - ref: messaging.operation.name
+      - ref: messaging.operation.type
         requirement_level: required
+      - ref: messaging.operation.name
+        requirement_level:
+          recommended: If the operation is not sufficiently described by `messaging.operation.type`.
       - ref: messaging.batch.message_count
         requirement_level:
           conditionally_required: If the span describes an operation on a batch of messages.

schema-next.yaml

@@ -24,7 +24,7 @@ versions:
         # https://github.com/open-telemetry/semantic-conventions/pull/913
         - rename_attributes:
             attribute_map:
-              messaging.operation: messaging.operation.name
+              messaging.operation: messaging.operation.type
         # https://github.com/open-telemetry/semantic-conventions/pull/866
         - rename_attributes:
             attribute_map: