From e74c9982f03c56b5a3be8d6b9c38aa52bd6005e9 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 13 Mar 2024 03:42:47 -0700 Subject: [PATCH] Introduce common `messaging.destination.partition.id` instead of per-system ones (#798) Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> --- .chloggen/798.yaml | 4 ++++ docs/attributes-registry/messaging.md | 12 ++++++++++-- docs/messaging/azure-messaging.md | 2 +- docs/messaging/kafka.md | 2 +- model/registry/deprecated/messaging.yaml | 11 +++++++++++ model/registry/messaging.yaml | 23 ++++++++--------------- model/trace/messaging.yaml | 12 ++++++++---- schema-next.yaml | 6 ++++++ 8 files changed, 49 insertions(+), 23 deletions(-) create mode 100644 .chloggen/798.yaml create mode 100644 model/registry/deprecated/messaging.yaml diff --git a/.chloggen/798.yaml b/.chloggen/798.yaml new file mode 100644 index 0000000000..95e89a8b1f --- /dev/null +++ b/.chloggen/798.yaml @@ -0,0 +1,4 @@ +change_type: breaking +component: messaging +note: Introduce common `messaging.destination.partition.id` instead of `messaging.kafka.destination.partition` +issues: [798] diff --git a/docs/attributes-registry/messaging.md b/docs/attributes-registry/messaging.md index 4d349029b7..7e3491b8d3 100644 --- a/docs/attributes-registry/messaging.md +++ b/docs/attributes-registry/messaging.md @@ -12,6 +12,7 @@ - [RocketMQ Attributes](#rocketmq-attributes) - [Azure Event Hubs Attributes](#azure-event-hubs-attributes) - [Azure Service Bus Attributes](#azure-service-bus-attributes) +- [Deprecated Messaging Attributes](#deprecated-messaging-attributes) @@ -24,6 +25,7 @@ | `messaging.client_id` | string | A unique identifier for the client that consumes or produces a message. | `client-5`; `myhost@8742@s8083jm` | | `messaging.destination.anonymous` | boolean | A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name). | | | `messaging.destination.name` | string | The message destination name [2] | `MyQueue`; `MyTopic` | +| `messaging.destination.partition.id` | string | The identifier of the partition messages are sent to or received from, unique within the `messaging.destination.name`. | `1` | | `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [3] | `/customers/{customerId}` | | `messaging.destination.temporary` | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | | `messaging.destination_publish.anonymous` | boolean | A boolean that is true if the publish message destination is anonymous (could be unnamed or have auto-generated name). | | @@ -93,7 +95,6 @@ size should be used. | Attribute | Type | Description | Examples | |---|---|---|---| | `messaging.kafka.consumer.group` | string | Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. | `my-group` | -| `messaging.kafka.destination.partition` | int | Partition the message is sent to. | `2` | | `messaging.kafka.message.key` | string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message.id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [1] | `myKey` | | `messaging.kafka.message.offset` | int | The offset of a record in the corresponding Kafka partition. | `42` | | `messaging.kafka.message.tombstone` | boolean | A boolean that is true if the message is a tombstone. | | @@ -148,7 +149,6 @@ size should be used. | Attribute | Type | Description | Examples | |---|---|---|---| | `messaging.eventhubs.consumer.group` | string | The name of the consumer group the event consumer is associated with. | `indexer` | -| `messaging.eventhubs.destination.partition.id` | string | The identifier of the partition messages are sent to or received from, unique to the Event Hub which contains it. | `1` | | `messaging.eventhubs.message.enqueued_time` | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | @@ -171,3 +171,11 @@ size should be used. | `dead_letter` | Message is sent to dead letter queue | | `defer` | Message is deferred | + +## Deprecated Messaging Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `messaging.kafka.destination.partition` | int | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
"Deprecated, use `messaging.destination.partition.id` instead." | `2` | + \ No newline at end of file diff --git a/docs/messaging/azure-messaging.md b/docs/messaging/azure-messaging.md index e7317d7b3a..e9b49cc5cf 100644 --- a/docs/messaging/azure-messaging.md +++ b/docs/messaging/azure-messaging.md @@ -54,8 +54,8 @@ The following additional attributes are defined: | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| +| [`messaging.destination.partition.id`](../attributes-registry/messaging.md) | string | "String representation of the partition id messages are sent to or received from, unique within the Event Hub." | `1` | Conditionally Required: If available. | | [`messaging.eventhubs.consumer.group`](../attributes-registry/messaging.md) | string | The name of the consumer group the event consumer is associated with. | `indexer` | Conditionally Required: If not default ("$Default"). | -| [`messaging.eventhubs.destination.partition.id`](../attributes-registry/messaging.md) | string | The identifier of the partition messages are sent to or received from, unique to the Event Hub which contains it. | `1` | Conditionally Required: If available. | | [`messaging.eventhubs.message.enqueued_time`](../attributes-registry/messaging.md) | int | The UTC epoch seconds at which the message has been accepted and stored in the entity. | `1701393730` | Recommended | diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index 47deec0d23..4f6866ed83 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -27,8 +27,8 @@ For Apache Kafka, the following additional attributes are defined: | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| +| [`messaging.destination.partition.id`](../attributes-registry/messaging.md) | string | "String representation of the partition id the message (or batch) is sent to or received from."" | `1` | Recommended | | [`messaging.kafka.consumer.group`](../attributes-registry/messaging.md) | string | Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. | `my-group` | Recommended | -| [`messaging.kafka.destination.partition`](../attributes-registry/messaging.md) | int | Partition the message is sent to. | `2` | Recommended | | [`messaging.kafka.message.key`](../attributes-registry/messaging.md) | string | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from `messaging.message.id` in that they're not unique. If the key is `null`, the attribute MUST NOT be set. [1] | `myKey` | Recommended | | [`messaging.kafka.message.offset`](../attributes-registry/messaging.md) | int | The offset of a record in the corresponding Kafka partition. | `42` | Recommended | | [`messaging.kafka.message.tombstone`](../attributes-registry/messaging.md) | boolean | A boolean that is true if the message is a tombstone. | | Conditionally Required: [2] | diff --git a/model/registry/deprecated/messaging.yaml b/model/registry/deprecated/messaging.yaml new file mode 100644 index 0000000000..015f428818 --- /dev/null +++ b/model/registry/deprecated/messaging.yaml @@ -0,0 +1,11 @@ +groups: + - id: attributes.messaging.deprecated + type: attribute_group + brief: "Describes deprecated messaging attributes." + attributes: + - id: messaging.kafka.destination.partition + type: int + brief: > + "Deprecated, use `messaging.destination.partition.id` instead." + examples: 2 + deprecated: "Replaced by `messaging.destination.partition.id`." diff --git a/model/registry/messaging.yaml b/model/registry/messaging.yaml index 4afd4d5320..5e6846abd7 100644 --- a/model/registry/messaging.yaml +++ b/model/registry/messaging.yaml @@ -66,6 +66,13 @@ groups: the broker doesn't have such notion, the original destination name SHOULD uniquely identify the broker. examples: ['MyQueue', 'MyTopic'] tag: messaging-generic + - id: destination.partition.id + type: string + stability: experimental + brief: > + The identifier of the partition messages are sent to or received from, unique within the `messaging.destination.name`. + examples: '1' + tag: messaging-generic - id: kafka.consumer.group type: string stability: experimental @@ -74,13 +81,6 @@ groups: Only applies to consumers, not producers. examples: 'my-group' tag: tech-specific-kafka - - id: kafka.destination.partition - type: int - stability: experimental - brief: > - Partition the message is sent to. - examples: 2 - tag: tech-specific-kafka - id: kafka.message.key type: string stability: experimental @@ -273,7 +273,7 @@ groups: type: string stability: experimental brief: > - The ordering key for a given message. If the attribute is not present, the message does not have an ordering key. + The ordering key for a given message. If the attribute is not present, the message does not have an ordering key. examples: 'ordering_key' tag: tech-specific-gcp-pubsub - id: system @@ -362,13 +362,6 @@ groups: The UTC epoch seconds at which the message has been accepted and stored in the entity. examples: 1701393730 tag: tech-specific-eventhubs - - id: eventhubs.destination.partition.id - type: string - stability: experimental - brief: > - The identifier of the partition messages are sent to or received from, unique to the Event Hub which contains it. - examples: '1' - tag: tech-specific-eventhubs - id: eventhubs.consumer.group type: string stability: experimental diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index 3a8543d540..362eaab9f4 100644 --- a/model/trace/messaging.yaml +++ b/model/trace/messaging.yaml @@ -109,12 +109,14 @@ groups: brief: > Attributes for Apache Kafka attributes: + - ref: messaging.destination.partition.id + brief: > + "String representation of the partition id the message (or batch) is sent to or received from."" + tag: tech-specific-kafka - ref: messaging.kafka.message.key tag: tech-specific-kafka - ref: messaging.kafka.consumer.group tag: tech-specific-kafka - - ref: messaging.kafka.destination.partition - tag: tech-specific-kafka - ref: messaging.kafka.message.offset tag: tech-specific-kafka - ref: messaging.kafka.message.tombstone @@ -186,10 +188,12 @@ groups: brief: > Attributes for Azure Event Hubs attributes: - - ref: messaging.eventhubs.message.enqueued_time - - ref: messaging.eventhubs.destination.partition.id + - ref: messaging.destination.partition.id + brief: > + "String representation of the partition id messages are sent to or received from, unique within the Event Hub." requirement_level: conditionally_required: If available. + - ref: messaging.eventhubs.message.enqueued_time - ref: messaging.eventhubs.consumer.group requirement_level: conditionally_required: If not default ("$Default"). diff --git a/schema-next.yaml b/schema-next.yaml index 441f34e983..b6e3a405d9 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -2,6 +2,12 @@ file_format: 1.1.0 schema_url: https://opentelemetry.io/schemas/next versions: next: + spans: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/798 + - rename_attributes: + attribute_map: + messaging.kafka.destination.partition: messaging.destination.partition.id metrics: changes: # https://github.com/open-telemetry/semantic-conventions/pull/484