From 4204c02ef036c9220b31b775db00f2f6dc9d18a6 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Fri, 3 May 2024 15:59:02 +0200 Subject: [PATCH] BREAKING: Rename `messaging.client_id` to `messaging.client.id` (#948) --- .chloggen/messaging-client-id.yaml | 4 ++++ docs/attributes-registry/messaging.md | 11 +++++++++++ docs/messaging/azure-messaging.md | 4 ++-- docs/messaging/kafka.md | 4 ++-- docs/messaging/messaging-spans.md | 2 +- docs/messaging/rocketmq.md | 2 +- model/registry/deprecated/messaging.yaml | 7 +++++++ model/registry/messaging.yaml | 2 +- model/trace/messaging.yaml | 2 +- schema-next.yaml | 4 ++++ 10 files changed, 34 insertions(+), 8 deletions(-) create mode 100644 .chloggen/messaging-client-id.yaml diff --git a/.chloggen/messaging-client-id.yaml b/.chloggen/messaging-client-id.yaml new file mode 100644 index 0000000000..07322fe724 --- /dev/null +++ b/.chloggen/messaging-client-id.yaml @@ -0,0 +1,4 @@ +change_type: breaking +component: messaging +note: Rename `messaging.client_id` to `messaging.client.id` +issues: [ 935 ] diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index 0ff400f546..bb16824c87 100644 --- a/docs/attributes-registry/messaging.md +++ b/docs/attributes-registry/messaging.md @@ -183,3 +183,14 @@ This group describes attributes specific to Azure Service Bus. | `abandon` | Message is abandoned | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `dead_letter` | Message is sent to dead letter queue | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `defer` | Message is deferred | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Deprecated Messaging Attributes + + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| [`messaging.client_id`](/docs/attributes-registry/messaging.md) | string | Deprecated, use `messaging.client.id` instead. | `client-5`; `myhost@8742@s8083jm` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.client.id`. | +| [`messaging.kafka.destination.partition`](/docs/attributes-registry/messaging.md) | 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`](/docs/attributes-registry/messaging.md) | string | Deprecated, use `messaging.operation.type` instead. | `publish`; `create`; `process` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `messaging.operation.type`. | + +>>>>>>> b66f1e5 (Update deprecated attributes) diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md index eea9ae1f81..bcae1c95ba 100644 --- a/docs/messaging/azure-messaging.md +++ b/docs/messaging/azure-messaging.md @@ -30,7 +30,7 @@ The following additional attributes are defined: | [`messaging.servicebus.disposition_status`](/docs/attributes-registry/messaging.md) | string | Describes the [settlement type](https://learn.microsoft.com/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock). | `complete`; `abandon`; `dead_letter` | `Conditionally Required` if and only if `messaging.operation` is `settle`. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.servicebus.message.delivery_count`](/docs/attributes-registry/messaging.md) | int | Number of deliveries that have been attempted for this message. | `2` | `Conditionally Required` [11] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [12] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`messaging.client_id`](/docs/attributes-registry/messaging.md) | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | `Recommended` If a client id is available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.client.id`](/docs/attributes-registry/messaging.md) | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | `Recommended` If a client id is available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) | string | The identifier of the partition messages are sent to or received from, unique within the `messaging.destination.name`. | `1` | `Recommended` When applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.message.body.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body in bytes. [13] | `1439` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.message.conversation_id`](/docs/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) | @@ -161,7 +161,7 @@ The following additional attributes are defined: | [`messaging.destination.temporary`](/docs/attributes-registry/messaging.md) | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | `Conditionally Required` [10] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.eventhubs.consumer.group`](/docs/attributes-registry/messaging.md) | string | The name of the consumer group the event consumer is associated with. | `indexer` | `Conditionally Required` If not default ("$Default"). | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`messaging.client_id`](/docs/attributes-registry/messaging.md) | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | `Recommended` If a client id is available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.client.id`](/docs/attributes-registry/messaging.md) | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | `Recommended` If a client id is available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.eventhubs.message.enqueued_time`](/docs/attributes-registry/messaging.md) | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.message.body.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body in bytes. [12] | `1439` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.message.conversation_id`](/docs/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) | diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index e53472a28f..518ccb8e19 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -42,7 +42,7 @@ For Apache Kafka producers, [`peer.service`](/docs/general/attributes.md#general The `service.name` of a Consumer's Resource SHOULD match the `peer.service` of the Producer, when the message is directly passed to another service. If an intermediary broker is present, `service.name` and `peer.service` will not be the same. -`messaging.client_id` SHOULD be set to the `client-id` of consumers, or to the `client.id` property of producers. +`messaging.client.id` SHOULD be set to the client name of a consumer or producer, which is unique for each individual instance. ## Examples @@ -78,7 +78,7 @@ Process CB: | Span Rcv2 | | `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | | `messaging.destination.name` | `"T1"` | `"T1"` | `"T1"` | `"T2"` | `"T2"` | | `messaging.operation.type` | | | `"process"` | | `"receive"` | -| `messaging.client_id` | | `"5"` | `"5"` | `"5"` | `"8"` | +| `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"` | | `messaging.kafka.destination.partition` | `"1"` | `"1"` | `"1"` | `"3"` | `"3"` | diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index d8246af684..530a8de492 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -295,7 +295,7 @@ as described in [Attributes specific to certain messaging systems](#attributes-s | [`messaging.destination.template`](/docs/attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [8] | `/customers/{customerId}` | `Conditionally Required` [9] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.temporary`](/docs/attributes-registry/messaging.md) | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | `Conditionally Required` [10] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`server.address`](/docs/attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Conditionally Required` If available. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`messaging.client_id`](/docs/attributes-registry/messaging.md) | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | `Recommended` If a client id is available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`messaging.client.id`](/docs/attributes-registry/messaging.md) | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | `Recommended` If a client id is available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.destination.partition.id`](/docs/attributes-registry/messaging.md) | string | The identifier of the partition messages are sent to or received from, unique within the `messaging.destination.name`. | `1` | `Recommended` When applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.message.body.size`](/docs/attributes-registry/messaging.md) | int | The size of the message body in bytes. [12] | `1439` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`messaging.message.conversation_id`](/docs/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) | diff --git a/docs/messaging/rocketmq.md b/docs/messaging/rocketmq.md index 6d99d19fab..c48d052fca 100644 --- a/docs/messaging/rocketmq.md +++ b/docs/messaging/rocketmq.md @@ -50,6 +50,6 @@ Specific attributes for Apache RocketMQ are defined below. | `transaction` | Transaction message | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`messaging.client_id` SHOULD be set to the client ID that is automatically generated by the Apache RocketMQ SDK. +`messaging.client.id` SHOULD be set to the client ID that is automatically generated by the Apache RocketMQ SDK. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md diff --git a/model/registry/deprecated/messaging.yaml b/model/registry/deprecated/messaging.yaml index 4f27d8e09a..2b3c0aad78 100644 --- a/model/registry/deprecated/messaging.yaml +++ b/model/registry/deprecated/messaging.yaml @@ -17,3 +17,10 @@ groups: Deprecated, use `messaging.operation.type` instead. examples: ["publish", "create", "process"] deprecated: "Replaced by `messaging.operation.type`." + - id: messaging.client_id + type: string + stability: experimental + brief: > + Deprecated, use `messaging.client.id` instead. + examples: ['client-5', 'myhost@8742@s8083jm'] + deprecated: "Replaced by `messaging.client.id`." diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index f22f58f155..554229ab67 100644 --- a/model/registry/messaging.yaml +++ b/model/registry/messaging.yaml @@ -13,7 +13,7 @@ groups: 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. examples: [0, 1, 2] - - id: client_id + - id: client.id type: string stability: experimental brief: > diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index 542edec127..02870702ab 100644 --- a/model/trace/messaging.yaml +++ b/model/trace/messaging.yaml @@ -62,7 +62,7 @@ groups: - ref: messaging.batch.message_count requirement_level: conditionally_required: If the span describes an operation on a batch of messages. - - ref: messaging.client_id + - ref: messaging.client.id requirement_level: recommended: If a client id is available - ref: messaging.destination.name diff --git a/schema-next.yaml b/schema-next.yaml index e344c34056..e759a899e2 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -12,6 +12,10 @@ versions: db.client.connections.max: db.client.connection.max db.client.connections.pending_requests: db.client.connection.pending_requests db.client.connections.timeouts: db.client.connection.timeouts + # https://github.com/open-telemetry/semantic-conventions/pull/948 + - rename_attributes: + attribute_map: + messaging.client_id: messaging.client.id # https://github.com/open-telemetry/semantic-conventions/pull/909 - rename_attributes: attribute_map: