BREAKING: Remove `messaging.consumer.id`, make `messaging.client_id` generic (#3336)

Fixes #2015 ## Changes Based on discussions in the messaging workgroup and in issue #2015, this PR proposes to remove `messaging.consumer.id`, and to replace both `messaging.kafka.client_id` and `messaging.rocketmq.client_id` with a generic `messaging.client_id`. `messaging.consumer.id` is defined to always be set to the `client_id` of the used messaging system, except for Kafka, where it was defined to be a combination of `messaging.kafka.client_id` and `messaging.kafka.consumer.group`, or just the latter if `messaging.kafka.client_id` is not available. With this definition, the semantics of `consumer.id` are different between messaging systems, and even different for different Kafka scenarios. The proposed `messaging.client_id` has consistent semantics ("an unique client id, when it is available"), and can be used instead of `messaging.consumer.id` in almost all cases. In addition to have consistent semantics, this also simplifies the semantic conventions, as instead of `messaging.consumer.id` `messaging.kafka.client_id` `messaging.rocketmq.client_id` there is now just: `messaging.client_id`.
2023-04-24 16:13:21 -07:00 · 2023-04-24 16:13:21 -07:00 · 15f3e529f1
parent 92a5b9ef64
commit 15f3e529f1
3 changed files with 110 additions and 23 deletions
--- a/schemas/1.21.0
+++ b/schemas/1.21.0
@ -0,0 +1,97 @@
+file_format: 1.1.0
+schema_url: https://opentelemetry.io/schemas/1.21.0
+versions:
+  1.21.0:
+    spans:
+      changes:
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3336
+        - rename_attributes:
+            attribute_map:
+              messaging.kafka.client_id: messaging.client_id
+              messaging.rocketmq.client_id: messaging.client_id
+  1.20.0:
+    spans:
+      changes:
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3272
+        - rename_attributes:
+            attribute_map:
+              net.app.protocol.name: net.protocol.name
+              net.app.protocol.version: net.protocol.version
+  1.19.0:
+    spans:
+      changes:
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3209
+        - rename_attributes:
+            attribute_map:
+              faas.execution: faas.invocation_id
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3188
+        - rename_attributes:
+            attribute_map:
+              faas.id: cloud.resource_id
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3190
+        - rename_attributes:
+            attribute_map:
+              http.user_agent: user_agent.original
+    resources:
+      changes:
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3190
+        - rename_attributes:
+            attribute_map:
+              browser.user_agent: user_agent.original
+  1.18.0:
+  1.17.0:
+    spans:
+      changes:
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/2957
+        - rename_attributes:
+            attribute_map:
+              messaging.consumer_id: messaging.consumer.id
+              messaging.protocol: net.app.protocol.name
+              messaging.protocol_version: net.app.protocol.version
+              messaging.destination: messaging.destination.name
+              messaging.temp_destination: messaging.destination.temporary
+              messaging.destination_kind: messaging.destination.kind
+              messaging.message_id: messaging.message.id
+              messaging.conversation_id: messaging.message.conversation_id
+              messaging.message_payload_size_bytes: messaging.message.payload_size_bytes
+              messaging.message_payload_compressed_size_bytes: messaging.message.payload_compressed_size_bytes
+              messaging.rabbitmq.routing_key: messaging.rabbitmq.destination.routing_key
+              messaging.kafka.message_key: messaging.kafka.message.key
+              messaging.kafka.partition: messaging.kafka.destination.partition
+              messaging.kafka.tombstone: messaging.kafka.message.tombstone
+              messaging.rocketmq.message_type: messaging.rocketmq.message.type
+              messaging.rocketmq.message_tag: messaging.rocketmq.message.tag
+              messaging.rocketmq.message_keys: messaging.rocketmq.message.keys
+              messaging.kafka.consumer_group: messaging.kafka.consumer.group
+  1.16.0:
+  1.15.0:
+    spans:
+      changes:
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/2743
+        - rename_attributes:
+            attribute_map:
+              http.retry_count: http.resend_count
+  1.14.0:
+  1.13.0:
+    spans:
+      changes:
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/2614
+        - rename_attributes:
+            attribute_map:
+              net.peer.ip: net.sock.peer.addr
+              net.host.ip: net.sock.host.addr
+  1.12.0:
+  1.11.0:
+  1.10.0:
+  1.9.0:
+  1.8.0:
+    spans:
+      changes:
+        - rename_attributes:
+            attribute_map:
+              db.cassandra.keyspace: db.name
+              db.hbase.namespace: db.name
+  1.7.0:
+  1.6.1:
+  1.5.0:
+  1.4.0:
--- a/semantic_conventions/trace/messaging.yaml
+++ b/semantic_conventions/trace/messaging.yaml
@ -122,6 +122,13 @@ 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
+        type: string
+        requirement_level:
+          recommended: If a client id is available
+        brief: >
+          A unique identifier for the client that consumes or produces a message.
+        examples: ['client-5', 'myhost@8742@s8083jm']
      - ref: messaging.message.id
        requirement_level:
          recommended: Only for spans that represent an operation on a single message.
@ -191,14 +198,6 @@ groups:
    span_kind: consumer
    brief: 'Semantic convention for a consumer of messages received from a messaging system'
    attributes:
-      - id: consumer.id
-        type: string
-        brief: >
-          The identifier for the consumer receiving a message. For Kafka, set it to
-          `{messaging.kafka.consumer.group} - {messaging.kafka.client_id}`, if both are present, or only
-          `messaging.kafka.consumer.group`. For brokers, such as RabbitMQ and Artemis, set it to the `client_id`
-          of the client consuming the message.
-        examples: 'mygroup - client-6'
      - ref: messaging.source.name
        requirement_level:
          conditionally_required: If the value applies to all messages in the batch.
@ -270,11 +269,6 @@ groups:
          Name of the Kafka Consumer Group that is handling the message.
          Only applies to consumers, not producers.
        examples: 'my-group'
-      - id: client_id
-        type: string
-        brief: >
-          Client Id for the Consumer or Producer that is handling the message.
-        examples: 'client-5'
      - id: destination.partition
        type: int
        brief: >
@ -315,12 +309,6 @@ groups:
        brief: >
          Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind.
        examples: 'myConsumerGroup'
-      - id: client_id
-        type: string
-        requirement_level: required
-        brief: >
-          The unique identifier for each client.
-        examples: 'myhost@8742@s8083jm'
      - id: message.delivery_timestamp
        type: int
        requirement_level:
--- a/specification/trace/semantic_conventions/messaging.md
+++ b/specification/trace/semantic_conventions/messaging.md
@ -189,6 +189,7 @@ The following operations related to messages are defined for these semantic conv
 | `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Required |
 | `messaging.operation` | string | A string identifying the kind of messaging operation as defined in the [Operation names](#operation-names) section above. [1] | `publish` | Required |
 | `messaging.batch.message_count` | int | The number of messages sent, received, or processed in the scope of the batching operation. [2] | `0`; `1`; `2` | Conditionally Required: [3] |
+| `messaging.client_id` | 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 |
 | `messaging.message.conversation_id` | string | The [conversation ID](#conversations) identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | Recommended: [4] |
 | `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [5] |
 | `messaging.message.payload_compressed_size_bytes` | int | The compressed size of the message payload in bytes. | `2048` | Recommended: [6] |
@ -291,7 +292,6 @@ The following additional attributes describe message consumer operations.
 <!-- semconv messaging.consumer -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `messaging.consumer.id` | string | The identifier for the consumer receiving a message. For Kafka, set it to `{messaging.kafka.consumer.group} - {messaging.kafka.client_id}`, if both are present, or only `messaging.kafka.consumer.group`. For brokers, such as RabbitMQ and Artemis, set it to the `client_id` of the client consuming the message. | `mygroup - client-6` | Recommended |
 | `messaging.destination.anonymous` | boolean | A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name). |  | Recommended: If known on consumer |
 | `messaging.destination.name` | string | The message destination name [1] | `MyQueue`; `MyTopic` | Recommended: If known on consumer |
 | `messaging.destination.temporary` | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. |  | Recommended: If known on consumer |
@ -363,7 +363,6 @@ For Apache Kafka, the following additional attributes are defined:
 |---|---|---|---|---|
 | `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` | Recommended |
 | `messaging.kafka.consumer.group` | string | Name of the Kafka Consumer Group that is handling the message. Only applies to consumers, not producers. | `my-group` | Recommended |
-| `messaging.kafka.client_id` | string | Client Id for the Consumer or Producer that is handling the message. | `client-5` | Recommended |
 | `messaging.kafka.destination.partition` | int | Partition the message is sent to. | `2` | Recommended |
 | `messaging.kafka.source.partition` | int | Partition the message is received from. | `2` | Recommended |
 | `messaging.kafka.message.offset` | int | The offset of a record in the corresponding Kafka partition. | `42` | Recommended |
@ -378,6 +377,8 @@ For Apache Kafka producers, [`peer.service`](./span-general.md#general-remote-se
 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.
+
 #### Apache RocketMQ

 Specific attributes for Apache RocketMQ are defined below.
@ -387,7 +388,6 @@ Specific attributes for Apache RocketMQ are defined below.
 |---|---|---|---|---|
 | `messaging.rocketmq.namespace` | string | Namespace of RocketMQ resources, resources in different namespaces are individual. | `myNamespace` | Required |
 | `messaging.rocketmq.client_group` | string | Name of the RocketMQ producer/consumer group that is handling the message. The client type is identified by the SpanKind. | `myConsumerGroup` | Required |
-| `messaging.rocketmq.client_id` | string | The unique identifier for each client. | `myhost@8742@s8083jm` | Required |
 | `messaging.rocketmq.message.delivery_timestamp` | int | The timestamp in milliseconds that the delay message is expected to be delivered to consumer. | `1665987217045` | Conditionally Required: [1] |
 | `messaging.rocketmq.message.delay_time_level` | int | The delay time level for delay message, which determines the message delay time. | `3` | Conditionally Required: [2] |
 | `messaging.rocketmq.message.group` | string | It is essential for FIFO message. Messages that belong to the same message group are always processed one by one within the same consumer group. | `myMessageGroup` | Conditionally Required: If the message type is FIFO. |
@ -417,6 +417,8 @@ Specific attributes for Apache RocketMQ are defined below.
 | `broadcasting` | Broadcasting consumption model |
 <!-- endsemconv -->

+`messaging.client_id` SHOULD be set to the client ID that is automatically generated by the Apache RocketMQ SDK.
+
 ## Examples

 ### Topic with multiple consumers
@ -479,9 +481,9 @@ Process CB:                           | Span Rcv2 |
 | `messaging.destination.name` | `"T1"` | | | | |
 | `messaging.source.name` |  | `"T1"` | `"T1"` | `"T2"` | `"T2"` |
 | `messaging.operation` |  |  | `"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"` |
-| `messaging.kafka.client_id` |  | `"5"` | `"5"` | `"5"` | `"8"` |
 | `messaging.kafka.partition` | `"1"` | `"1"` | `"1"` | `"3"` | `"3"` |
 | `messaging.kafka.message.offset` | `"12"` | `"12"` | `"12"` | `"32"` | `"32"` |