From 05a374ff0ea456f5e265da26d04399fc58a67c06 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Tue, 9 Apr 2024 10:22:52 +0200 Subject: [PATCH 1/6] Rename `messaging.operation` to `messaging.operation.name` --- docs/attributes-registry/messaging.md | 4 ++-- docs/messaging/gcp-pubsub.md | 2 +- docs/messaging/kafka.md | 4 ++-- docs/messaging/messaging-spans.md | 10 +++++----- model/registry/messaging.yaml | 4 ++-- model/trace/messaging.yaml | 2 +- 6 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index ba7f61aec3..90d9bbfca6 100644 --- a/docs/attributes-registry/messaging.md +++ b/docs/attributes-registry/messaging.md @@ -34,7 +34,7 @@ | `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 | A string identifying the name 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 +55,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.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. | Value | Description | Stability | |---|---|---| diff --git a/docs/messaging/gcp-pubsub.md b/docs/messaging/gcp-pubsub.md index d1a7274b1b..fa17e505e3 100644 --- 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.name` | `"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 index 88beccf2d4..f43b00a53b 100644 --- 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.name` 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.name` | | | `"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 index cfae7e750b..8f1340c31a 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -281,7 +281,7 @@ as described in [Attributes specific to certain messaging systems](#attributes-s | 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.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.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) | @@ -351,7 +351,7 @@ If a messaging operation involved multiple network calls (for example retries), **[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. -`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.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. | Value | Description | Stability | |---|---|---| @@ -469,7 +469,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.name` | `"publish"` | `"process"` | `"process"` | | `messaging.message.id` | `"a"` | `"a"`| `"a"` | ### Batch receiving @@ -507,7 +507,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.name` | `"publish"` | `"publish"` | `"receive"` | | `messaging.message.id` | `"a1"` | `"a2"` | | | `messaging.batch.message_count` | | | 2 | @@ -552,7 +552,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.name` | `"create"` | `"create"` | `"publish"` | `"receive"` | `"receive"` | | `messaging.message.id` | `"a1"` | `"a2"` | | `"a1"` | `"a2"` | | `messaging.batch.message_count` | | | 2 | | | diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index 4938ddd045..d907a7759c 100644 --- 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.name type: allow_custom_values: true members: @@ -173,7 +173,7 @@ groups: stability: experimental stability: experimental brief: > - A string identifying the kind of messaging operation. + A string identifying the name of the messaging operation. note: If a custom value is used, it MUST be of low cardinality. tag: messaging-generic - id: rabbitmq.destination.routing_key diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index 2c669cce82..915205cdd8 100644 --- a/model/trace/messaging.yaml +++ b/model/trace/messaging.yaml @@ -54,7 +54,7 @@ groups: messaging systems. extends: messaging.attributes.common attributes: - - ref: messaging.operation + - ref: messaging.operation.name requirement_level: required - ref: messaging.batch.message_count requirement_level: From 74e1a41a19185758d0daf413c3217517f3378f79 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Tue, 9 Apr 2024 10:27:00 +0200 Subject: [PATCH 2/6] Add schema and changelog --- .chloggen/890.yaml | 4 ++++ schema-next.yaml | 4 ++++ 2 files changed, 8 insertions(+) create mode 100644 .chloggen/890.yaml diff --git a/.chloggen/890.yaml b/.chloggen/890.yaml new file mode 100644 index 0000000000..fc7db3a244 --- /dev/null +++ b/.chloggen/890.yaml @@ -0,0 +1,4 @@ +change_type: breaking +component: messaging +note: Rename `messaging.operation` to `messaging.operation.name`. +issues: [ 890 ] diff --git a/schema-next.yaml b/schema-next.yaml index b893a50d4e..a8ae4251ce 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -21,6 +21,10 @@ versions: - rename_attributes: attribute_map: db.operation: db.operation.name + # https://github.com/open-telemetry/semantic-conventions/pull/913 + - rename_attributes: + attribute_map: + messaging.operation: messaging.operation.name # https://github.com/open-telemetry/semantic-conventions/pull/866 - rename_attributes: attribute_map: From 2a2c32b9a00747b3ff1464192189ba9c4cfed1f8 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Tue, 9 Apr 2024 14:19:21 +0200 Subject: [PATCH 3/6] Add to deprecated attributes --- docs/attributes-registry/messaging.md | 13 +++++++++ model/registry/deprecated/messaging.yaml | 37 ++++++++++++++++++++++++ 2 files changed, 50 insertions(+) diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index 90d9bbfca6..ac6205f7fd 100644 --- a/docs/attributes-registry/messaging.md +++ b/docs/attributes-registry/messaging.md @@ -178,4 +178,17 @@ 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)
Replaced by `messaging.destination.partition.id`. | +| `messaging.operation` | string | A string identifying the kind of messaging operation. [1] | `publish` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.operation.name`. | + +**[1]:** 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. + +| Value | Description | Stability | +|---|---|---| +| `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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `process` | One or more messages are delivered to or processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `settle` | One or more messages are settled. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | \ No newline at end of file diff --git a/model/registry/deprecated/messaging.yaml b/model/registry/deprecated/messaging.yaml index a2675c7c47..87838e9ea8 100644 --- a/model/registry/deprecated/messaging.yaml +++ b/model/registry/deprecated/messaging.yaml @@ -10,3 +10,40 @@ groups: examples: 2 deprecated: "Replaced by `messaging.destination.partition.id`." stability: experimental + - id: messaging.operation + type: + allow_custom_values: true + members: + - id: publish + value: "publish" + brief: > + 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. + stability: experimental + - id: create + value: "create" + brief: > + A message is created. + "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. + stability: experimental + - id: receive + value: "receive" + brief: > + One or more messages are requested by a consumer. + This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. + stability: experimental + - id: deliver + value: "process" + brief: > + One or more messages are delivered to or processed by a consumer. + stability: experimental + - id: settle + value: "settle" + brief: > + One or more messages are settled. + stability: experimental + stability: experimental + brief: > + A string identifying the kind of messaging operation. + note: If a custom value is used, it MUST be of low cardinality. + deprecated: "Replaced by `messaging.operation.name`." From 22d28be9d6773210c8da0d2c13bdfc56db01ac20 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Tue, 9 Apr 2024 14:25:29 +0200 Subject: [PATCH 4/6] Fix deprecation table --- docs/attributes-registry/messaging.md | 16 ++-------- model/registry/deprecated/messaging.yaml | 38 +++--------------------- 2 files changed, 6 insertions(+), 48 deletions(-) diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index ac6205f7fd..37ac561632 100644 --- a/docs/attributes-registry/messaging.md +++ b/docs/attributes-registry/messaging.md @@ -177,18 +177,6 @@ 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)
Replaced by `messaging.destination.partition.id`. | -| `messaging.operation` | string | A string identifying the kind of messaging operation. [1] | `publish` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.operation.name`. | - -**[1]:** 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. - -| Value | Description | Stability | -|---|---|---| -| `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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `create` | A message is created. "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `receive` | One or more messages are requested by a consumer. This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `process` | One or more messages are delivered to or processed by a consumer. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `settle` | One or more messages are settled. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `messaging.kafka.destination.partition` | int | Deprecated, use `messaging.destination.partition.id` instead. | `2` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
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)
Replaced by `messaging.operation.name`. | \ No newline at end of file diff --git a/model/registry/deprecated/messaging.yaml b/model/registry/deprecated/messaging.yaml index 87838e9ea8..7084e54f49 100644 --- a/model/registry/deprecated/messaging.yaml +++ b/model/registry/deprecated/messaging.yaml @@ -6,44 +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: - allow_custom_values: true - members: - - id: publish - value: "publish" - brief: > - 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. - stability: experimental - - id: create - value: "create" - brief: > - A message is created. - "Create" spans always refer to a single message and are used to provide a unique creation context for messages in batch publishing scenarios. - stability: experimental - - id: receive - value: "receive" - brief: > - One or more messages are requested by a consumer. - This operation refers to pull-based scenarios, where consumers explicitly call methods of messaging SDKs to receive messages. - stability: experimental - - id: deliver - value: "process" - brief: > - One or more messages are delivered to or processed by a consumer. - stability: experimental - - id: settle - value: "settle" - brief: > - One or more messages are settled. - stability: experimental + type: string stability: experimental brief: > - A string identifying the kind of messaging operation. - note: If a custom value is used, it MUST be of low cardinality. + Deprecated, use `messaging.operation.name` instead. + examples: ["publish", "create", "process"] deprecated: "Replaced by `messaging.operation.name`." From 69a85803697e64e3bdca26dfb326737b8f9ed398 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Fri, 12 Apr 2024 12:26:14 +0200 Subject: [PATCH 5/6] PR comments --- docs/attributes-registry/messaging.md | 7 ++-- docs/messaging/azure-messaging.md | 18 --------- docs/messaging/messaging-spans.md | 48 ++++++++++++++---------- model/registry/deprecated/messaging.yaml | 4 +- model/registry/messaging.yaml | 11 +++++- model/trace/messaging.yaml | 5 ++- schema-next.yaml | 2 +- 7 files changed, 48 insertions(+), 47 deletions(-) diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index 37ac561632..7e83f76a3c 100644 --- 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.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)
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)
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)
Replaced by `messaging.operation.type`. | \ No newline at end of file diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md index ad68bdf0c5..8028640677 100644 --- 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 ` {messaging.servicebus.disposition_status}` pattern. - For example, `my-queue complete` or `my-queue abandon`. -- Spans names for `publish` operations SHOULD follow the ` send` pattern. -- Spans for `create`, `receive`, and `publish` operations SHOULD follow the general ` ` 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 ` checkpoint` pattern (matching Event Hubs terminology). -- Spans names for `publish` operations SHOULD follow the ` send` pattern. -- Spans for `create`, `receive`, and `publish` operations SHOULD follow the general ` ` pattern. - ### Span attributes The following additional attributes are defined: diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 8f1340c31a..4b4f450e5c 100644 --- 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: ``` ``` +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: + +``` + +``` + 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 `` 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 | 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 | | | diff --git a/model/registry/deprecated/messaging.yaml b/model/registry/deprecated/messaging.yaml index 7084e54f49..4f27d8e09a 100644 --- a/model/registry/deprecated/messaging.yaml +++ b/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`." diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index d907a7759c..32e603d1dc 100644 --- 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.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 diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index 915205cdd8..f12a96b1df 100644 --- a/model/trace/messaging.yaml +++ b/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. diff --git a/schema-next.yaml b/schema-next.yaml index a8ae4251ce..430901253a 100644 --- a/schema-next.yaml +++ b/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: From 08f5b6ab286759ece4e06b6ca83ebd444a3cccee Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Fri, 12 Apr 2024 12:29:34 +0200 Subject: [PATCH 6/6] PR comments --- .chloggen/890.yaml | 2 +- docs/messaging/gcp-pubsub.md | 2 +- docs/messaging/kafka.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.chloggen/890.yaml b/.chloggen/890.yaml index fc7db3a244..4c3e5ce030 100644 --- a/.chloggen/890.yaml +++ b/.chloggen/890.yaml @@ -1,4 +1,4 @@ change_type: breaking component: messaging -note: Rename `messaging.operation` to `messaging.operation.name`. +note: Rename `messaging.operation` to `messaging.operation.type`, add `messaging.operation.name`. issues: [ 890 ] diff --git a/docs/messaging/gcp-pubsub.md b/docs/messaging/gcp-pubsub.md index fa17e505e3..b586668d69 100644 --- 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.name` | `"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 index f43b00a53b..5002947f9e 100644 --- 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.name` 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.name` | | | `"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"` |