From 69a85803697e64e3bdca26dfb326737b8f9ed398 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Fri, 12 Apr 2024 12:26:14 +0200 Subject: [PATCH] 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: