From c6967bf155dc9362b2113b1986de2bba2de78d0c Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Thu, 27 Jun 2024 11:33:07 +0200 Subject: [PATCH 1/6] WIP --- .../migration-guide.md | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 docs/messaging/supplementary-guidelines/migration-guide.md diff --git a/docs/messaging/supplementary-guidelines/migration-guide.md b/docs/messaging/supplementary-guidelines/migration-guide.md new file mode 100644 index 0000000000..0aaf23139a --- /dev/null +++ b/docs/messaging/supplementary-guidelines/migration-guide.md @@ -0,0 +1,36 @@ +# Messaging semantic convention stability migration guide + +Due to the significant number of modifications and the extensive user base +affected by them, existing messaging instrumentations published by +OpenTelemetry are required to implement a migration plan that will assist users in +transitioning to the stable messaging semantic conventions. + +Specifically, when existing messaging instrumentations published by OpenTelemetry are +updated to the stable messaging semantic conventions, they: + +- SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` in + their existing major version, which accepts: + - `messaging` - emit the stable messaging conventions, and stop emitting + the old messaging conventions that the instrumentation emitted previously. + - `messaging/dup` - emit both the old and the stable messaging conventions, + allowing for a phased rollout of the stable semantic conventions. + - The default behavior (in the absence of one of these values) is to continue + emitting whatever version of the old messaging conventions the + instrumentation was emitting previously. +- Need to maintain (security patching at a minimum) their existing major version + for at least six months after it starts emitting both sets of conventions. +- May drop the environment variable in their next major version and emit only + the stable messaging conventions. + +## Summary of changes + +This section summarizes the changes made to the HTTP semantic conventions +from +[v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/messaging/README.md). +to +[v1.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/messaging/README.md). + +### Common messaging attributes + +| Change | Comments | +| ------ | -------- | From 535ac5a461d9f245fd602a7e7ce50bfd6f8918c7 Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Mon, 1 Jul 2024 16:44:22 +0200 Subject: [PATCH 2/6] WIP --- .../migration-guide.md | 404 +++++++++++++++++- 1 file changed, 401 insertions(+), 3 deletions(-) diff --git a/docs/messaging/supplementary-guidelines/migration-guide.md b/docs/messaging/supplementary-guidelines/migration-guide.md index 0aaf23139a..74d1a01f4e 100644 --- a/docs/messaging/supplementary-guidelines/migration-guide.md +++ b/docs/messaging/supplementary-guidelines/migration-guide.md @@ -24,7 +24,7 @@ updated to the stable messaging semantic conventions, they: ## Summary of changes -This section summarizes the changes made to the HTTP semantic conventions +This section summarizes the changes made to the messaging semantic conventions from [v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/messaging/README.md). to @@ -32,5 +32,403 @@ to ### Common messaging attributes -| Change | Comments | -| ------ | -------- | +#### New attributes + + +| New attributes | +| -------------- | +| `messaging.destination.partition.id` | +| `messaging.operation.name` | +| `error.type` | +| `server.port` | + + +#### Changed attributes + + +| Attribute change | Comments | +| ---------------- | -------- | +| `messaging.system` from string to enum | | +| `messaging.operation` → `messaging.operation.type` | | +| `messaging.client_id` → `messaging.client.id` | | + + +### Removed attributes + + +| Removed attributes | +| -------------- | +| `network.transport` | +| `network.type` | +| `network.protocol.name` | +| `network.protocol.version` | + + +### Kafka attributes + +#### New attributes + + +| New attributes | +| -------------- | +| `messaging.operation.type` | +| `error.type` | +| `messaging.batch.message_count` | +| `messaging.destination.name` | +| `server.address` | +| `messaging.client.id` | +| `messaging.message.body.size` | +| `messaging.message.id` | +| `messaging.operation.name` | +| `server.port` | + + +#### Changed attributes + + +| Attribute change | Comments | +| ---------------- | -------- | +| `messaging.kafka.partition` → `messaging.destination.partition.id` | | + + + +### RabbitMQ attributes + +#### New attributes + + +| New attributes | +| -------------- | +| `messaging.rabbitmq.message.delivery_tag` | +| `network.peer.address` | +| `network.peer.port` | +| `messaging.operation.type` | +| `error.type` | +| `messaging.destination.name` | +| `server.address` | +| `messaging.message.body.size` | +| `messaging.message.conversation_id` | +| `messaging.message.id` | +| `messaging.operation.name` | +| `server.port` | + + +#### RocketMQ attributes + +##### New attributes + + +| New attributes | +| -------------- | +| `messaging.operation.type` | +| `error.type` | +| `messaging.batch.message_count` | +| `messaging.destination.name` | +| `server.address` | +| `messaging.client.id` | +| `messaging.message.body.size` | +| `messaging.message.id` | +| `messaging.operation.name` | +| `server.port` | + + +### Azure Servicebus + +#### New attributes + + +| New attributes | +| -------------- | +| `messaging.operation.type` | +| `error.type` | +| `messaging.batch.message_count` | +| `messaging.destination.name` | +| `messaging.servicebus.destination.subscription_name` | +| `messaging.servicebus.disposition_status` | +| `messaging.servicebus.message.delivery_count` | +| `server.address` | +| `messaging.message.conversation_id` | +| `messaging.message.id` | +| `messaging.operation.name` | +| `messaging.servicebus.message.enqueued_time` | +| `messaging.destination.partition.id` | +| `messaging.eventhubs.consumer.group` | +| `messaging.eventhubs.message.enqueued_time` | + + +### Azure Event Hubs + +#### New attributes + + +| New attributes | +| -------------- | +| `messaging.operation.type` | +| `error.type` | +| `messaging.batch.message_count` | +| `messaging.destination.name` | +| `messaging.destination.partition.id` | +| `messaging.eventhubs.consumer.group` | +| `server.address` | +| `messaging.servicebus.message.enqueued_time` | +| `messaging.message.id` | +| `messaging.operation.name` | +| `server.port` | + + +### GCP Pubsub attributes + +#### New attributes + + +| New attributes | +| -------------- | +| `messaging.operation.type` | +| `error.type` | +| `messaging.batch.message_count` | +| `messaging.destination.name` | +| `messaging.gcp_pubsub.message.ordering_key` | +| `server.address` | +| `messaging.gcp_pubsub.message.ack_deadline` | +| `messaging.gcp_pubsub.message.ack_id` | +| `messaging.gcp_pubsub.message.delivery_attempt` | +| `messaging.message.id` | +| `messaging.operation.name` | +| `server.port` | + + +## Migrating from a version prior to v1.24.0? + +In addition to the changes made to the Messaging semantic conventions +from +[v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/messaging/README.md) +to +[v1.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/messaging/README.md), +there are additional changes if you are migrating to v1.TODO from a version prior to v1.24.0. + +### Migrating from `<= v1.23.0` + +- Initial version of new trace structure [#284](https://github.com/open-telemetry/semantic-conventions/pull/284) + - Using links to correlate producer to consumers + - Concept of create spans + - Model traces for pull and push based scenarios" + +### Migrating from `<= v1.22.0` + +#### Common messaging attributes + +##### New attributes + + +| New attributes | +| -------------- | +| `messaging.message.envelope.size` | +| `messaging.destination_publish.name` | +| `messaging.destination_publish.anonymous` | + + +##### Changed attributes + + +| Attribute change | Comments | +| ---------------- | -------- | +| `messaging.message.payload_size_bytes` → `messaging.message.body.size` | | +| `server.socket.address` → `network.peer.address` | | +| `server.socket.port` → `network.peer.port` | | + + +##### Removed attributes + + +| Removed attributes | +| -------------- | +| `server.socket.domain` | +| `messaging.message.payload_compressed_size_bytes` | + + +### Migrating from `<= v1.21.0` + +#### Common messaging attributes + +##### New attributes + + +| New attributes | +| -------------- | +| `network.transport` | +| `network.type` | + + +##### Changed attributes + + +| Attribute change | Comments | +| ---------------- | -------- | +| `messaging.consumer.id` → `messaging.client_id` | | +| `net.peer.name` → `server.address` | | +| `net.protocol.name` → `network.protocol.name` | | +| `net.protocol.version` → `network.protocol.version` | | +| `net.sock.peer.addr` → `server.socket.address` | | +| `net.sock.peer.name` → `server.socket.domain` | | +| `net.sock.peer.port` → `server.socket.port` | | + + +#### Removed attributes + + +| Removed attributes | +| -------------- | +| `net.sock.family` | +| `messaging.source.anonymous` | +| `messaging.source.name` | +| `messaging.source.template` | +| `messaging.source.temporary` | + + +#### Kafka attributes + +##### Changed attributes + + +| Attribute change | Comments | +| ---------------- | -------- | +| `messaging.kafka.client_id` → `messaging.client_id` | | + + +##### Removed attributes + + +| Removed attributes | +| -------------- | +| `messaging.kafka.source.partition` | + + +#### RocketMQ attributes + +##### Changed attributes + + +| Attribute change | Comments | +| ---------------- | -------- | +| `messaging.rocketmq.client_id` → `messaging.client_id` | | + + +### Migrating from `<= v1.20.0` + +#### Common messaging attributes + +##### Changed attributes + + +| Attribute change | Comments | +| ---------------- | -------- | +| `net.app.protocol.name` → `net.protocol.name` | | +| `net.app.protocol.version` → `net.protocol.version` | | + + +##### Removed attributes + + +| Removed attributes | +| -------------- | +| `messaging.destination.kind` | +| `messaging.source.kind` | + + +### Migrating from `<= v1.19.0` + +No changes + +### Migrating from `<= v1.18.0` + +No changes + +### Migrating from `<= v1.17.0` + +#### Common messaging attributes + +##### New attributes + + +| New attributes | +| -------------- | +| `messaging.batch.message_count` | +| `messaging.destination.anonymous` | +| `messaging.destination.template` | +| `messaging.source.anonymous` | +| `messaging.source.kind` | +| `messaging.source.name` | +| `messaging.source.template` | +| `messaging.source.temporary` | + + +##### Changed attributes + + +| Attribute change | Comments | +| ---------------- | -------- | +| `messaging.destination` → `messaging.destination.name` | | +| `messaging.destination_kind` → `messaging.destination.kind` | | +| `messaging.temp_destination` → `messaging.destination.temporary` | | +| `messaging.protocol` → `net.app.protocol.name` | | +| `messaging.protocol_version` → `net.app.protocol.version` | | +| `messaging.consumer_id` → `messaging.consumer.id` | | +| `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` | | + + +##### Removed attributes + + +| Removed attributes | +| -------------- | +| `messaging.url` | + + +#### Kafka attributes + +##### New attributes + + +| New attributes | +| -------------- | +| `messaging.kafka.source.partition` | + + +##### Changed attributes + + +| Attribute change | Comments | +| ---------------- | -------- | +| `messaging.kafka.message_key` → `messaging.kafka.message.key` | | +| `messaging.kafka.consumer_group` → `messaging.kafka.consumer.group` | | +| `messaging.kafka.partition` → `messaging.kafka.destination.partition` | | +| `messaging.kafka.tombstone` → `messaging.kafka.message.tombstone` | | + + +#### RabbitMQ attributes + +##### Changed attributes + + +| Attribute change | Comments | +| ---------------- | -------- | +| `messaging.rabbitmq.routing_key` → `messaging.rabbitmq.destination.routing_key` | | + + +#### RocketMQ attributes + +##### Changed attributes + + +| Attribute change | Comments | +| ---------------- | -------- | +| `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.rocketmq.delivery_timestamp` → `messaging.rocketmq.message.delivery_timestamp` | | +| `messaging.rocketmq.delay_time_level` → `messaging.rocketmq.message.delay_time_level` | | +| `messaging.rocketmq.message_group` → `messaging.rocketmq.message.group` | | + From 5e8276550b15d47b623c49f62007dd86f53ed85a Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Mon, 23 Sep 2024 13:25:48 +0200 Subject: [PATCH 3/6] Restructure document --- .../migration-guide.md | 554 +++++++++--------- 1 file changed, 288 insertions(+), 266 deletions(-) diff --git a/docs/messaging/supplementary-guidelines/migration-guide.md b/docs/messaging/supplementary-guidelines/migration-guide.md index 74d1a01f4e..e66ae6df21 100644 --- a/docs/messaging/supplementary-guidelines/migration-guide.md +++ b/docs/messaging/supplementary-guidelines/migration-guide.md @@ -25,410 +25,432 @@ updated to the stable messaging semantic conventions, they: ## Summary of changes This section summarizes the changes made to the messaging semantic conventions -from -[v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/messaging/README.md). -to +from a range of versions. Each starting version shows all the changes required +to bring the conventions to [v1.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/messaging/README.md). -### Common messaging attributes +### From v1.26.0 -#### New attributes +#### ![new](https://img.shields.io/badge/new-green?style=flat) New attributes | New attributes | | -------------- | -| `messaging.destination.partition.id` | -| `messaging.operation.name` | -| `error.type` | -| `server.port` | +| `messaging.consumer.group.name` | +| `messaging.destination.subscription.name` | -#### Changed attributes +#### ![changed](https://img.shields.io/badge/changed-orange?style=flat) Changed attributes -| Attribute change | Comments | -| ---------------- | -------- | -| `messaging.system` from string to enum | | -| `messaging.operation` → `messaging.operation.type` | | -| `messaging.client_id` → `messaging.client.id` | | +| Old | New | +| --- | --- | +| `messaging.eventhubs.consumer.group` | `messaging.consumer.group.name` | +| `messaging.kafka.consumer.group` | `messaging.consumer.group.name` | +| `messaging.kafka.message.offset` | `messaging.kafka.offset` | +| `messaging.rocketmq.client_group` | `messaging.consumer.group.name` | +| `messaging.servicebus.destination.subscription_name` | `messaging.destination.subscription.name` | -### Removed attributes +#### ![removed](https://img.shields.io/badge/removed-red?style=flat) Removed attributes | Removed attributes | -| -------------- | -| `network.transport` | -| `network.type` | -| `network.protocol.name` | -| `network.protocol.version` | +| ------------------ | +| `messaging.destination_publish.anonymous` | +| `messaging.destination_publish.name` | -### Kafka attributes +### From v1.25.0 -#### New attributes +#### ![new](https://img.shields.io/badge/new-green?style=flat) New attributes | New attributes | | -------------- | -| `messaging.operation.type` | -| `error.type` | -| `messaging.batch.message_count` | -| `messaging.destination.name` | -| `server.address` | -| `messaging.client.id` | -| `messaging.message.body.size` | -| `messaging.message.id` | +| `messaging.consumer.group.name` | +| `messaging.destination.subscription.name` | +| `messaging.gcp_pubsub.message.ack_deadline` | +| `messaging.gcp_pubsub.message.ack_id` | +| `messaging.gcp_pubsub.message.delivery_attempt` | | `messaging.operation.name` | -| `server.port` | -#### Changed attributes +#### ![changed](https://img.shields.io/badge/changed-orange?style=flat) Changed attributes -| Attribute change | Comments | -| ---------------- | -------- | -| `messaging.kafka.partition` → `messaging.destination.partition.id` | | - +| Old | New | +| --- | --- | +| `messaging.client_id` | `messaging.client.id` | +| `messaging.eventhubs.consumer.group` | `messaging.consumer.group.name` | +| `messaging.kafka.consumer.group` | `messaging.consumer.group.name` | +| `messaging.kafka.message.offset` | `messaging.kafka.offset` | +| `messaging.operation` | `messaging.operation.type` | +| `messaging.rocketmq.client_group` | `messaging.consumer.group.name` | +| `messaging.servicebus.destination.subscription_name` | `messaging.destination.subscription.name` | -### RabbitMQ attributes - -#### New attributes +#### ![removed](https://img.shields.io/badge/removed-red?style=flat) Removed attributes -| New attributes | -| -------------- | -| `messaging.rabbitmq.message.delivery_tag` | -| `network.peer.address` | -| `network.peer.port` | -| `messaging.operation.type` | -| `error.type` | -| `messaging.destination.name` | -| `server.address` | -| `messaging.message.body.size` | -| `messaging.message.conversation_id` | -| `messaging.message.id` | -| `messaging.operation.name` | -| `server.port` | +| Removed attributes | +| ------------------ | +| `messaging.destination_publish.anonymous` | +| `messaging.destination_publish.name` | -#### RocketMQ attributes +### From v1.24.0 -##### New attributes +#### ![new](https://img.shields.io/badge/new-green?style=flat) New attributes | New attributes | | -------------- | -| `messaging.operation.type` | -| `error.type` | -| `messaging.batch.message_count` | -| `messaging.destination.name` | -| `server.address` | -| `messaging.client.id` | -| `messaging.message.body.size` | -| `messaging.message.id` | +| `messaging.consumer.group.name` | +| `messaging.destination.partition.id` | +| `messaging.destination.subscription.name` | +| `messaging.eventhubs.message.enqueued_time` | +| `messaging.gcp_pubsub.message.ack_deadline` | +| `messaging.gcp_pubsub.message.ack_id` | +| `messaging.gcp_pubsub.message.delivery_attempt` | | `messaging.operation.name` | -| `server.port` | - - -### Azure Servicebus - -#### New attributes - - -| New attributes | -| -------------- | -| `messaging.operation.type` | -| `error.type` | -| `messaging.batch.message_count` | -| `messaging.destination.name` | -| `messaging.servicebus.destination.subscription_name` | +| `messaging.rabbitmq.message.delivery_tag` | | `messaging.servicebus.disposition_status` | | `messaging.servicebus.message.delivery_count` | -| `server.address` | -| `messaging.message.conversation_id` | -| `messaging.message.id` | -| `messaging.operation.name` | | `messaging.servicebus.message.enqueued_time` | -| `messaging.destination.partition.id` | -| `messaging.eventhubs.consumer.group` | -| `messaging.eventhubs.message.enqueued_time` | -### Azure Event Hubs +#### ![changed](https://img.shields.io/badge/changed-orange?style=flat) Changed attributes + + +| Old | New | +| --- | --- | +| `messaging.client_id` | `messaging.client.id` | +| `messaging.kafka.consumer.group` | `messaging.consumer.group.name` | +| `messaging.kafka.destination.partition` | `messaging.destination.partition.id` | +| `messaging.kafka.message.offset` | `messaging.kafka.offset` | +| `messaging.operation` | `messaging.operation.type` | +| `messaging.rocketmq.client_group` | `messaging.consumer.group.name` | + -#### New attributes +#### ![removed](https://img.shields.io/badge/removed-red?style=flat) Removed attributes -| New attributes | -| -------------- | -| `messaging.operation.type` | -| `error.type` | -| `messaging.batch.message_count` | -| `messaging.destination.name` | -| `messaging.destination.partition.id` | -| `messaging.eventhubs.consumer.group` | -| `server.address` | -| `messaging.servicebus.message.enqueued_time` | -| `messaging.message.id` | -| `messaging.operation.name` | -| `server.port` | +| Removed attributes | +| ------------------ | +| `messaging.destination_publish.anonymous` | +| `messaging.destination_publish.name` | +| `network.protocol.name` | +| `network.protocol.version` | +| `network.transport` | +| `network.type` | -### GCP Pubsub attributes +### From v1.23.0 and v1.22.0 -#### New attributes +#### ![new](https://img.shields.io/badge/new-green?style=flat) New attributes | New attributes | | -------------- | -| `messaging.operation.type` | | `error.type` | -| `messaging.batch.message_count` | -| `messaging.destination.name` | -| `messaging.gcp_pubsub.message.ordering_key` | -| `server.address` | +| `messaging.consumer.group.name` | +| `messaging.destination.partition.id` | +| `messaging.destination.subscription.name` | +| `messaging.eventhubs.message.enqueued_time` | | `messaging.gcp_pubsub.message.ack_deadline` | | `messaging.gcp_pubsub.message.ack_id` | | `messaging.gcp_pubsub.message.delivery_attempt` | -| `messaging.message.id` | +| `messaging.gcp_pubsub.message.ordering_key` | | `messaging.operation.name` | +| `messaging.rabbitmq.message.delivery_tag` | +| `messaging.servicebus.disposition_status` | +| `messaging.servicebus.message.delivery_count` | +| `messaging.servicebus.message.enqueued_time` | | `server.port` | -## Migrating from a version prior to v1.24.0? - -In addition to the changes made to the Messaging semantic conventions -from -[v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/messaging/README.md) -to -[v1.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/messaging/README.md), -there are additional changes if you are migrating to v1.TODO from a version prior to v1.24.0. +#### ![changed](https://img.shields.io/badge/changed-orange?style=flat) Changed attributes -### Migrating from `<= v1.23.0` + +| Old | New | +| --- | --- | +| `messaging.client_id` | `messaging.client.id` | +| `messaging.kafka.consumer.group` | `messaging.consumer.group.name` | +| `messaging.kafka.destination.partition` | `messaging.destination.partition.id` | +| `messaging.kafka.message.offset` | `messaging.kafka.offset` | +| `messaging.operation` | `messaging.operation.type` | +| `messaging.rocketmq.client_group` | `messaging.consumer.group.name` | + -- Initial version of new trace structure [#284](https://github.com/open-telemetry/semantic-conventions/pull/284) - - Using links to correlate producer to consumers - - Concept of create spans - - Model traces for pull and push based scenarios" +#### ![removed](https://img.shields.io/badge/removed-red?style=flat) Removed attributes -### Migrating from `<= v1.22.0` + +| Removed attributes | +| ------------------ | +| `messaging.destination_publish.anonymous` | +| `messaging.destination_publish.name` | +| `network.protocol.name` | +| `network.protocol.version` | +| `network.transport` | +| `network.type` | + -#### Common messaging attributes +### From v1.21.0 -##### New attributes +#### ![new](https://img.shields.io/badge/new-green?style=flat) New attributes | New attributes | | -------------- | +| `error.type` | +| `messaging.consumer.group.name` | +| `messaging.destination.partition.id` | +| `messaging.destination.subscription.name` | +| `messaging.eventhubs.message.enqueued_time` | +| `messaging.gcp_pubsub.message.ack_deadline` | +| `messaging.gcp_pubsub.message.ack_id` | +| `messaging.gcp_pubsub.message.delivery_attempt` | +| `messaging.gcp_pubsub.message.ordering_key` | | `messaging.message.envelope.size` | -| `messaging.destination_publish.name` | -| `messaging.destination_publish.anonymous` | +| `messaging.operation.name` | +| `messaging.rabbitmq.message.delivery_tag` | +| `messaging.servicebus.disposition_status` | +| `messaging.servicebus.message.delivery_count` | +| `messaging.servicebus.message.enqueued_time` | +| `server.port` | -##### Changed attributes +#### ![changed](https://img.shields.io/badge/changed-orange?style=flat) Changed attributes -| Attribute change | Comments | -| ---------------- | -------- | -| `messaging.message.payload_size_bytes` → `messaging.message.body.size` | | -| `server.socket.address` → `network.peer.address` | | -| `server.socket.port` → `network.peer.port` | | +| Old | New | +| --- | --- | +| `messaging.client_id` | `messaging.client.id` | +| `messaging.kafka.consumer.group` | `messaging.consumer.group.name` | +| `messaging.kafka.destination.partition` | `messaging.destination.partition.id` | +| `messaging.kafka.message.offset` | `messaging.kafka.offset` | +| `messaging.message.payload_compressed_size_bytes` | `messaging.message.body.size` | +| `messaging.message.payload_size_bytes` | `messaging.message.envelope.size` | +| `messaging.operation` | `messaging.operation.type` | +| `messaging.rocketmq.client_group` | `messaging.consumer.group.name` | +| `server.socket.address` | `network.peer.address` | +| `server.socket.port` | `network.peer.port` | -##### Removed attributes +#### ![removed](https://img.shields.io/badge/removed-red?style=flat) Removed attributes | Removed attributes | -| -------------- | +| ------------------ | +| `network.protocol.name` | +| `network.protocol.version` | +| `network.transport` | +| `network.type` | | `server.socket.domain` | -| `messaging.message.payload_compressed_size_bytes` | -### Migrating from `<= v1.21.0` - -#### Common messaging attributes +### From v1.20.0 -##### New attributes +#### ![new](https://img.shields.io/badge/new-green?style=flat) New attributes | New attributes | | -------------- | -| `network.transport` | -| `network.type` | +| `error.type` | +| `messaging.consumer.group.name` | +| `messaging.destination.partition.id` | +| `messaging.destination.subscription.name` | +| `messaging.eventhubs.message.enqueued_time` | +| `messaging.gcp_pubsub.message.ack_deadline` | +| `messaging.gcp_pubsub.message.ack_id` | +| `messaging.gcp_pubsub.message.delivery_attempt` | +| `messaging.gcp_pubsub.message.ordering_key` | +| `messaging.message.envelope.size` | +| `messaging.operation.name` | +| `messaging.rabbitmq.message.delivery_tag` | +| `messaging.servicebus.disposition_status` | +| `messaging.servicebus.message.delivery_count` | +| `messaging.servicebus.message.enqueued_time` | +| `server.port` | -##### Changed attributes +#### ![changed](https://img.shields.io/badge/changed-orange?style=flat) Changed attributes -| Attribute change | Comments | -| ---------------- | -------- | -| `messaging.consumer.id` → `messaging.client_id` | | -| `net.peer.name` → `server.address` | | -| `net.protocol.name` → `network.protocol.name` | | -| `net.protocol.version` → `network.protocol.version` | | -| `net.sock.peer.addr` → `server.socket.address` | | -| `net.sock.peer.name` → `server.socket.domain` | | -| `net.sock.peer.port` → `server.socket.port` | | +| Old | New | +| --- | --- | +| `messaging.client_id` | `messaging.client.id` | +| `messaging.consumer.id` | `messaging.client.id` | +| `messaging.kafka.client_id` | `messaging.client.id` | +| `messaging.kafka.consumer.group` | `messaging.consumer.group.name` | +| `messaging.kafka.destination.partition` | `messaging.destination.partition.id` | +| `messaging.kafka.message.offset` | `messaging.kafka.offset` | +| `messaging.message.payload_compressed_size_bytes` | `messaging.message.body.size` | +| `messaging.message.payload_size_bytes` | `messaging.message.envelope.size` | +| `messaging.operation` | `messaging.operation.type` | +| `messaging.rocketmq.client_group` | `messaging.consumer.group.name` | +| `messaging.rocketmq.client_id` | `messaging.client.id` | +| `net.peer.name` | `server.address` | +| `net.sock.peer.addr` | `network.peer.address` | +| `net.sock.peer.port` | `network.peer.port` | -#### Removed attributes +#### ![removed](https://img.shields.io/badge/removed-red?style=flat) Removed attributes | Removed attributes | -| -------------- | -| `net.sock.family` | +| ------------------ | +| `messaging.kafka.source.partition` | | `messaging.source.anonymous` | | `messaging.source.name` | | `messaging.source.template` | | `messaging.source.temporary` | +| `net.protocol.name` | +| `net.protocol.version` | +| `net.sock.family` | +| `net.sock.peer.name` | -#### Kafka attributes - -##### Changed attributes - - -| Attribute change | Comments | -| ---------------- | -------- | -| `messaging.kafka.client_id` → `messaging.client_id` | | - +### From v1.19.0 and v1.18.0 v1.17.0 -##### Removed attributes +#### ![new](https://img.shields.io/badge/new-green?style=flat) New attributes -| Removed attributes | +| New attributes | | -------------- | -| `messaging.kafka.source.partition` | - - -#### RocketMQ attributes - -##### Changed attributes - - -| Attribute change | Comments | -| ---------------- | -------- | -| `messaging.rocketmq.client_id` → `messaging.client_id` | | +| `error.type` | +| `messaging.consumer.group.name` | +| `messaging.destination.partition.id` | +| `messaging.destination.subscription.name` | +| `messaging.eventhubs.message.enqueued_time` | +| `messaging.gcp_pubsub.message.ack_deadline` | +| `messaging.gcp_pubsub.message.ack_id` | +| `messaging.gcp_pubsub.message.delivery_attempt` | +| `messaging.gcp_pubsub.message.ordering_key` | +| `messaging.message.envelope.size` | +| `messaging.operation.name` | +| `messaging.rabbitmq.message.delivery_tag` | +| `messaging.servicebus.disposition_status` | +| `messaging.servicebus.message.delivery_count` | +| `messaging.servicebus.message.enqueued_time` | +| `server.port` | -### Migrating from `<= v1.20.0` - -#### Common messaging attributes - -##### Changed attributes +#### ![changed](https://img.shields.io/badge/changed-orange?style=flat) Changed attributes -| Attribute change | Comments | -| ---------------- | -------- | -| `net.app.protocol.name` → `net.protocol.name` | | -| `net.app.protocol.version` → `net.protocol.version` | | +| Old | New | +| --- | --- | +| `message.servicebus.destination.subscription_name` | `messaging.destination.subscription.name` | +| `messaging.client_id` | `messaging.client.id` | +| `messaging.consumer.id` | `messaging.client.id` | +| `messaging.evenhubs.consumer.group` | `messaging.consumer.group.name` | +| `messaging.kafka.client_id` | `messaging.client.id` | +| `messaging.kafka.consumer.group` | `messaging.consumer.group.name` | +| `messaging.kafka.message.offset` | `messaging.kafka.offset` | +| `messaging.kafka.partition` | `messaging.destination.partition.id` | +| `messaging.message.payload_size_bytes` | `messaging.message.envelope.size` | +| `messaging.operation` | `messaging.operation.type` | +| `messaging.rocketmq.client_group` | `messaging.consumer.group.name` | +| `messaging.rocketmq.client_id` | `messaging.client.id` | +| `net.peer.name` | `server.address` | +| `net.sock.peer.addr` | `network.peer.address` | +| `net.sock.peer.port` | `network.peer.port` | -##### Removed attributes +#### ![removed](https://img.shields.io/badge/removed-red?style=flat) Removed attributes | Removed attributes | -| -------------- | +| ------------------ | +| `destination_publish.anonymous` | | `messaging.destination.kind` | +| `messaging.kafka.source.partition` | +| `messaging.message.payload_compressed_size_bytes` | +| `messaging.source.anonymous` | | `messaging.source.kind` | +| `messaging.source.name` | +| `messaging.source.template` | +| `messaging.source.temporary` | +| `net.app.protocol.name` | +| `net.app.protocol.version` | +| `net.sock.family` | +| `net.sock.peer.name` | +| `network.transport` | +| `network.type` | -### Migrating from `<= v1.19.0` - -No changes +### From v1.16 -### Migrating from `<= v1.18.0` - -No changes - -### Migrating from `<= v1.17.0` - -#### Common messaging attributes - -##### New attributes +#### ![new](https://img.shields.io/badge/new-green?style=flat) New attributes | New attributes | | -------------- | +| `error.type` | | `messaging.batch.message_count` | +| `messaging.consumer.group.name` | | `messaging.destination.anonymous` | +| `messaging.destination.partition.id` | +| `messaging.destination.subscription.name` | | `messaging.destination.template` | -| `messaging.source.anonymous` | -| `messaging.source.kind` | -| `messaging.source.name` | -| `messaging.source.template` | -| `messaging.source.temporary` | +| `messaging.eventhubs.message.enqueued_time` | +| `messaging.gcp_pubsub.message.ack_deadline` | +| `messaging.gcp_pubsub.message.ack_id` | +| `messaging.gcp_pubsub.message.delivery_attempt` | +| `messaging.gcp_pubsub.message.ordering_key` | +| `messaging.message.envelope.size` | +| `messaging.operation.name` | +| `messaging.rabbitmq.message.delivery_tag` | +| `messaging.servicebus.disposition_status` | +| `messaging.servicebus.message.delivery_count` | +| `messaging.servicebus.message.enqueued_time` | +| `server.port` | -##### Changed attributes +#### ![changed](https://img.shields.io/badge/changed-orange?style=flat) Changed attributes -| Attribute change | Comments | -| ---------------- | -------- | -| `messaging.destination` → `messaging.destination.name` | | -| `messaging.destination_kind` → `messaging.destination.kind` | | -| `messaging.temp_destination` → `messaging.destination.temporary` | | -| `messaging.protocol` → `net.app.protocol.name` | | -| `messaging.protocol_version` → `net.app.protocol.version` | | -| `messaging.consumer_id` → `messaging.consumer.id` | | -| `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` | | +| Old | New | +| --- | --- | +| `messaging.consumer_id` | `messaging.client.id` | +| `messaging.conversation_id` | `messaging.message.conversation_id` | +| `messaging.destination` | `messaging.destination.name` | +| `messaging.kafka.client_id` | `messaging.client.id` | +| `messaging.kafka.consumer_group` | `messaging.consumer.group.name` | +| `messaging.kafka.message_key` | `messaging.kafka.message.key` | +| `messaging.kafka.message.offset` | `messaging.kafka.offset` | +| `messaging.kafka.partition` | `messaging.destination.partition.id` | +| `messaging.kafka.tombstone` | `messaging.kafka.message.tombstone` | +| `messaging.message_id` | `messaging.message.id` | +| `messaging.message_payload_compressed_size_bytes` | `messaging.message.body.size` | +| `messaging.message_payload_size_bytes` | `messaging.message.envelope.size` | +| `messaging.operation` | `messaging.operation.type` | +| `messaging.rabbitmq.routing_key` | `messaging.rabbitmq.destination.routing_key` | +| `messaging.rocketmq.client_group` | `messaging.consumer.group.name` | +| `messaging.rocketmq.client_id` | `messaging.client.id` | +| `messaging.rocketmq.delay_time_level` | `messaging.rocketmq.message.delay_time_level` | +| `messaging.rocketmq.delivery_timestamp` | `messaging.rocketmq.message.delivery_timestamp` | +| `messaging.rocketmq.message_group` | `messaging.rocketmq.message.group` | +| `messaging.rocketmq.message_keys` | `messaging.rocketmq.message.keys` | +| `messaging.rocketmq.message_tag` | `messaging.rocketmq.message.tag` | +| `messaging.rocketmq.message_type` | `messaging.rocketmq.message.type` | +| `messaging.temp_destination` | `messaging.destination.temporary` | +| `net.peer.name` | `server.address` | +| `net.sock.peer.addr` | `network.peer.address` | +| `net.sock.peer.port` | `network.peer.port` | -##### Removed attributes +#### ![removed](https://img.shields.io/badge/removed-red?style=flat) Removed attributes | Removed attributes | -| -------------- | +| ------------------ | | `messaging.url` | - - -#### Kafka attributes - -##### New attributes - - -| New attributes | -| -------------- | -| `messaging.kafka.source.partition` | - - -##### Changed attributes - - -| Attribute change | Comments | -| ---------------- | -------- | -| `messaging.kafka.message_key` → `messaging.kafka.message.key` | | -| `messaging.kafka.consumer_group` → `messaging.kafka.consumer.group` | | -| `messaging.kafka.partition` → `messaging.kafka.destination.partition` | | -| `messaging.kafka.tombstone` → `messaging.kafka.message.tombstone` | | - - -#### RabbitMQ attributes - -##### Changed attributes - - -| Attribute change | Comments | -| ---------------- | -------- | -| `messaging.rabbitmq.routing_key` → `messaging.rabbitmq.destination.routing_key` | | - - -#### RocketMQ attributes - -##### Changed attributes - - -| Attribute change | Comments | -| ---------------- | -------- | -| `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.rocketmq.delivery_timestamp` → `messaging.rocketmq.message.delivery_timestamp` | | -| `messaging.rocketmq.delay_time_level` → `messaging.rocketmq.message.delay_time_level` | | -| `messaging.rocketmq.message_group` → `messaging.rocketmq.message.group` | | +| `messaging.destination_kind` | +| `net.sock.family` | +| `net.sock.peer.name` | +| `messaging.protocol` | +| `messaging.protocol_version` | From 0902ece84cb93799a6eb8043b43af532fd366eb3 Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Mon, 23 Sep 2024 13:37:16 +0200 Subject: [PATCH 4/6] remove headings --- .../migration-guide.md | 132 +++++++----------- 1 file changed, 51 insertions(+), 81 deletions(-) diff --git a/docs/messaging/supplementary-guidelines/migration-guide.md b/docs/messaging/supplementary-guidelines/migration-guide.md index e66ae6df21..a6c0325714 100644 --- a/docs/messaging/supplementary-guidelines/migration-guide.md +++ b/docs/messaging/supplementary-guidelines/migration-guide.md @@ -1,4 +1,8 @@ -# Messaging semantic convention stability migration guide + + +# Messaging semantic convention stability migration Due to the significant number of modifications and the extensive user base affected by them, existing messaging instrumentations published by @@ -22,6 +26,20 @@ updated to the stable messaging semantic conventions, they: - May drop the environment variable in their next major version and emit only the stable messaging conventions. + + +- [Summary of changes](#summary-of-changes) + - [Migrating from v1.26.0](#migrating-from-v1260) + - [Migrating from v1.25.0](#migrating-from-v1250) + - [Migrating from v1.24.0](#migrating-from-v1240) + - [Migrating from v1.23.0 and v1.22.0](#migrating-from-v1230-and-v1220) + - [Migrating from v1.21.0](#migrating-from-v1210) + - [Migrating from v1.20.0](#migrating-from-v1200) + - [Migrating from v1.19.0 and v1.18.0 v1.17.0](#migrating-from-v1190-and-v1180-v1170) + - [Migrating from v1.16](#migrating-from-v116) + + + ## Summary of changes This section summarizes the changes made to the messaging semantic conventions @@ -29,21 +47,17 @@ from a range of versions. Each starting version shows all the changes required to bring the conventions to [v1.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/messaging/README.md). -### From v1.26.0 - -#### ![new](https://img.shields.io/badge/new-green?style=flat) New attributes +### Migrating from v1.26.0 -| New attributes | +| New attributes ![new](https://img.shields.io/badge/new-green?style=flat) | | -------------- | | `messaging.consumer.group.name` | | `messaging.destination.subscription.name` | -#### ![changed](https://img.shields.io/badge/changed-orange?style=flat) Changed attributes - -| Old | New | +| Old ![changed](https://img.shields.io/badge/changed-orange?style=flat) | New | | --- | --- | | `messaging.eventhubs.consumer.group` | `messaging.consumer.group.name` | | `messaging.kafka.consumer.group` | `messaging.consumer.group.name` | @@ -52,21 +66,17 @@ to bring the conventions to | `messaging.servicebus.destination.subscription_name` | `messaging.destination.subscription.name` | -#### ![removed](https://img.shields.io/badge/removed-red?style=flat) Removed attributes - -| Removed attributes | +| Removed attributes ![removed](https://img.shields.io/badge/removed-red?style=flat) | | ------------------ | | `messaging.destination_publish.anonymous` | | `messaging.destination_publish.name` | -### From v1.25.0 - -#### ![new](https://img.shields.io/badge/new-green?style=flat) New attributes +### Migrating from v1.25.0 -| New attributes | +| New attributes ![new](https://img.shields.io/badge/new-green?style=flat) | | -------------- | | `messaging.consumer.group.name` | | `messaging.destination.subscription.name` | @@ -76,10 +86,8 @@ to bring the conventions to | `messaging.operation.name` | -#### ![changed](https://img.shields.io/badge/changed-orange?style=flat) Changed attributes - -| Old | New | +| Old ![changed](https://img.shields.io/badge/changed-orange?style=flat) | New | | --- | --- | | `messaging.client_id` | `messaging.client.id` | | `messaging.eventhubs.consumer.group` | `messaging.consumer.group.name` | @@ -90,21 +98,17 @@ to bring the conventions to | `messaging.servicebus.destination.subscription_name` | `messaging.destination.subscription.name` | -#### ![removed](https://img.shields.io/badge/removed-red?style=flat) Removed attributes - -| Removed attributes | +| Removed attributes ![removed](https://img.shields.io/badge/removed-red?style=flat) | | ------------------ | | `messaging.destination_publish.anonymous` | | `messaging.destination_publish.name` | -### From v1.24.0 - -#### ![new](https://img.shields.io/badge/new-green?style=flat) New attributes +### Migrating from v1.24.0 -| New attributes | +| New attributes ![new](https://img.shields.io/badge/new-green?style=flat) | | -------------- | | `messaging.consumer.group.name` | | `messaging.destination.partition.id` | @@ -120,10 +124,8 @@ to bring the conventions to | `messaging.servicebus.message.enqueued_time` | -#### ![changed](https://img.shields.io/badge/changed-orange?style=flat) Changed attributes - -| Old | New | +| Old ![changed](https://img.shields.io/badge/changed-orange?style=flat) | New | | --- | --- | | `messaging.client_id` | `messaging.client.id` | | `messaging.kafka.consumer.group` | `messaging.consumer.group.name` | @@ -133,10 +135,8 @@ to bring the conventions to | `messaging.rocketmq.client_group` | `messaging.consumer.group.name` | -#### ![removed](https://img.shields.io/badge/removed-red?style=flat) Removed attributes - -| Removed attributes | +| Removed attributes ![removed](https://img.shields.io/badge/removed-red?style=flat) | | ------------------ | | `messaging.destination_publish.anonymous` | | `messaging.destination_publish.name` | @@ -146,12 +146,10 @@ to bring the conventions to | `network.type` | -### From v1.23.0 and v1.22.0 - -#### ![new](https://img.shields.io/badge/new-green?style=flat) New attributes +### Migrating from v1.23.0 and v1.22.0 -| New attributes | +| New attributes ![new](https://img.shields.io/badge/new-green?style=flat) | | -------------- | | `error.type` | | `messaging.consumer.group.name` | @@ -170,10 +168,8 @@ to bring the conventions to | `server.port` | -#### ![changed](https://img.shields.io/badge/changed-orange?style=flat) Changed attributes - -| Old | New | +| Old ![changed](https://img.shields.io/badge/changed-orange?style=flat) | New | | --- | --- | | `messaging.client_id` | `messaging.client.id` | | `messaging.kafka.consumer.group` | `messaging.consumer.group.name` | @@ -183,10 +179,8 @@ to bring the conventions to | `messaging.rocketmq.client_group` | `messaging.consumer.group.name` | -#### ![removed](https://img.shields.io/badge/removed-red?style=flat) Removed attributes - -| Removed attributes | +| Removed attributes ![removed](https://img.shields.io/badge/removed-red?style=flat) | | ------------------ | | `messaging.destination_publish.anonymous` | | `messaging.destination_publish.name` | @@ -196,12 +190,10 @@ to bring the conventions to | `network.type` | -### From v1.21.0 - -#### ![new](https://img.shields.io/badge/new-green?style=flat) New attributes +### Migrating from v1.21.0 -| New attributes | +| New attributes ![new](https://img.shields.io/badge/new-green?style=flat) | | -------------- | | `error.type` | | `messaging.consumer.group.name` | @@ -221,10 +213,8 @@ to bring the conventions to | `server.port` | -#### ![changed](https://img.shields.io/badge/changed-orange?style=flat) Changed attributes - -| Old | New | +| Old ![changed](https://img.shields.io/badge/changed-orange?style=flat) | New | | --- | --- | | `messaging.client_id` | `messaging.client.id` | | `messaging.kafka.consumer.group` | `messaging.consumer.group.name` | @@ -238,10 +228,8 @@ to bring the conventions to | `server.socket.port` | `network.peer.port` | -#### ![removed](https://img.shields.io/badge/removed-red?style=flat) Removed attributes - -| Removed attributes | +| Removed attributes ![removed](https://img.shields.io/badge/removed-red?style=flat) | | ------------------ | | `network.protocol.name` | | `network.protocol.version` | @@ -250,12 +238,10 @@ to bring the conventions to | `server.socket.domain` | -### From v1.20.0 - -#### ![new](https://img.shields.io/badge/new-green?style=flat) New attributes +### Migrating from v1.20.0 -| New attributes | +| New attributes ![new](https://img.shields.io/badge/new-green?style=flat) | | -------------- | | `error.type` | | `messaging.consumer.group.name` | @@ -275,10 +261,8 @@ to bring the conventions to | `server.port` | -#### ![changed](https://img.shields.io/badge/changed-orange?style=flat) Changed attributes - -| Old | New | +| Old ![changed](https://img.shields.io/badge/changed-orange?style=flat) | New | | --- | --- | | `messaging.client_id` | `messaging.client.id` | | `messaging.consumer.id` | `messaging.client.id` | @@ -296,10 +280,8 @@ to bring the conventions to | `net.sock.peer.port` | `network.peer.port` | -#### ![removed](https://img.shields.io/badge/removed-red?style=flat) Removed attributes - -| Removed attributes | +| Removed attributes ![removed](https://img.shields.io/badge/removed-red?style=flat) | | ------------------ | | `messaging.kafka.source.partition` | | `messaging.source.anonymous` | @@ -312,12 +294,10 @@ to bring the conventions to | `net.sock.peer.name` | -### From v1.19.0 and v1.18.0 v1.17.0 - -#### ![new](https://img.shields.io/badge/new-green?style=flat) New attributes +### Migrating from v1.19.0 and v1.18.0 v1.17.0 -| New attributes | +| New attributes ![new](https://img.shields.io/badge/new-green?style=flat) | | -------------- | | `error.type` | | `messaging.consumer.group.name` | @@ -337,10 +317,8 @@ to bring the conventions to | `server.port` | -#### ![changed](https://img.shields.io/badge/changed-orange?style=flat) Changed attributes - -| Old | New | +| Old ![changed](https://img.shields.io/badge/changed-orange?style=flat) | New | | --- | --- | | `message.servicebus.destination.subscription_name` | `messaging.destination.subscription.name` | | `messaging.client_id` | `messaging.client.id` | @@ -359,10 +337,8 @@ to bring the conventions to | `net.sock.peer.port` | `network.peer.port` | -#### ![removed](https://img.shields.io/badge/removed-red?style=flat) Removed attributes - -| Removed attributes | +| Removed attributes ![removed](https://img.shields.io/badge/removed-red?style=flat) | | ------------------ | | `destination_publish.anonymous` | | `messaging.destination.kind` | @@ -381,12 +357,10 @@ to bring the conventions to | `network.type` | -### From v1.16 - -#### ![new](https://img.shields.io/badge/new-green?style=flat) New attributes +### Migrating from v1.16 -| New attributes | +| New attributes ![new](https://img.shields.io/badge/new-green?style=flat) | | -------------- | | `error.type` | | `messaging.batch.message_count` | @@ -409,10 +383,8 @@ to bring the conventions to | `server.port` | -#### ![changed](https://img.shields.io/badge/changed-orange?style=flat) Changed attributes - -| Old | New | +| Old ![changed](https://img.shields.io/badge/changed-orange?style=flat) | New | | --- | --- | | `messaging.consumer_id` | `messaging.client.id` | | `messaging.conversation_id` | `messaging.message.conversation_id` | @@ -442,10 +414,8 @@ to bring the conventions to | `net.sock.peer.port` | `network.peer.port` | -#### ![removed](https://img.shields.io/badge/removed-red?style=flat) Removed attributes - -| Removed attributes | +| Removed attributes ![removed](https://img.shields.io/badge/removed-red?style=flat) | | ------------------ | | `messaging.url` | | `messaging.destination_kind` | From 5443556bba3507c08e85615725f32e6124d49054 Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Mon, 23 Sep 2024 13:38:11 +0200 Subject: [PATCH 5/6] Move to non-normative folder --- .../migration-guide.md => non-normative/messaging-migration.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{messaging/supplementary-guidelines/migration-guide.md => non-normative/messaging-migration.md} (100%) diff --git a/docs/messaging/supplementary-guidelines/migration-guide.md b/docs/non-normative/messaging-migration.md similarity index 100% rename from docs/messaging/supplementary-guidelines/migration-guide.md rename to docs/non-normative/messaging-migration.md From 5dd878c1eca124541c4a856f8bb44220c95cc5ec Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Mon, 14 Oct 2024 13:47:36 +0200 Subject: [PATCH 6/6] Add other migration details --- docs/non-normative/messaging-migration.md | 67 +++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/docs/non-normative/messaging-migration.md b/docs/non-normative/messaging-migration.md index a6c0325714..85e6690604 100644 --- a/docs/non-normative/messaging-migration.md +++ b/docs/non-normative/messaging-migration.md @@ -29,6 +29,9 @@ updated to the stable messaging semantic conventions, they: - [Summary of changes](#summary-of-changes) + - [Span name](#span-name) + - [Operation](#operation) + - [Span Kind](#span-kind) - [Migrating from v1.26.0](#migrating-from-v1260) - [Migrating from v1.25.0](#migrating-from-v1250) - [Migrating from v1.24.0](#migrating-from-v1240) @@ -37,6 +40,7 @@ updated to the stable messaging semantic conventions, they: - [Migrating from v1.20.0](#migrating-from-v1200) - [Migrating from v1.19.0 and v1.18.0 v1.17.0](#migrating-from-v1190-and-v1180-v1170) - [Migrating from v1.16](#migrating-from-v116) + - [Metrics](#metrics) @@ -47,6 +51,46 @@ from a range of versions. Each starting version shows all the changes required to bring the conventions to [v1.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/messaging/README.md). +### Span name + +The recommended span name has changed to `{messaging.operation.name} {destination}`, where the `{destination}` SHOULD describe the entity +that the operation is performed against and SHOULD adhere to one of the following values, provided they are accessible: + +- `messaging.destination.template` SHOULD be used when it is available. +- `messaging.destination.name` SHOULD be used when the destination is known to be neither temporary nor anonymous. +- `server.address:server.port` SHOULD be used only for operations not targeting any specific destination(s). + +References: + +- [Span name](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/messaging/messaging-spans.md#span-name) + +### Operation + +The previously `messaging.operation` attribute is renamed to `messaging.operation.type` and has the following defined values: + +- `create` +- `send` +- `receive` +- `process` +- `settle` + +References: + +- [Operation types](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/messaging/messaging-spans.md#operation-types) + +### Span Kind + +The recommended span kind has changed and is now based on the `messaging.operation.type`. + +- `create` -> `PRODUCER` +- `send` -> `PRODUCER` if the context of the "Send" span is used as creation context, otherwise `CLIENT` +- `receive` -> `CLIENT` +- `process` -> `CONSUMER` + +References: + +- [Span kind](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/messaging/messaging-spans.md#span-kind) + ### Migrating from v1.26.0 @@ -424,3 +468,26 @@ to bring the conventions to | `messaging.protocol` | | `messaging.protocol_version` | + +### Metrics + +Messaging client metrics were initially added in Semantic Conventions +version `v1.24.0`. Instrumentations that implemented these experimental +metrics should adapt and migrate to the latest version: + +Common metrics: + +- [messaging.client.operation.duration](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/messaging/messaging-metrics.md#metric-messagingclientoperationduration) + +Producer metrics: + +- [messaging.client.sent.messages](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/messaging/messaging-metrics.md#metric-messagingclientsentmessages) + +Consumer metrics: + +- [messaging.client.consumed.messages](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/messaging/messaging-metrics.md#metric-messagingclientconsumedmessages) +- [messaging.process.duration](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/messaging/messaging-metrics.md#metric-messagingprocessduration) + +References: + +- [Messaging Client Metrics](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/messaging/messaging-metrics.md)