Messaging semconv migration guide

[joaopgrassi]

Fixes #1183

Changes

Migration guide similar to the one done for HTTP, for when the messaging conventions become stable.

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• Change log entry added, according to the guidelines in When to add a changelog entry.
  • If your PR does not need a change log, start the PR title with [chore]
• schema-next.yaml updated with changes to existing conventions.

[lmolkova]

I wonder if it would be easier if we had one (or a few) "migrate from any version" table?
Then people can easily find whatever attributes they are currently using and see what finally happened to them.

I tried to summarize all changes here (but probably missed a thing or two):

Change	Comments
New: error.type
New: messaging.gcp_pubsub.message.ack_deadline
New: messaging.gcp_pubsub.message.delivery_attempt
New: messaging.gcp_pubsub.message.ordering_key
New: messaging.gcp_pubsub.message.ack_id
New: messaging.gcp_pubsub.message.delivery_attempt
messaging.eventhubs.consumer.group -> messaging.consumer.group.name
New: messaging.eventhubs.message.enqueued_time
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.partition -> messaging.destination.partition.id
messaging.kafka.source.partition -> messaging.destination.partition.id
messaging.kafka.tombstone -> messaging.kafka.message.tombstone
messaging.rabbitmq.routing_key -> messaging.rabbitmq.destination.routing_key
New: messaging.rabbitmq.message.delivery_tag
messaging.rocketmq.client_id -> messaging.client.id
messaging.rocketmq.message_type -> messaging.rocketmq.message.type
messaging.rocketmq.message_tag -> messaging.rocketmq.message.tag
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.message_group
messaging.servicebus.destination.subscription_name -> messaging.destination.subscription.name
New: messaging.servicebus.disposition_status
New: messaging.servicebus.message.delivery_count
New: messaging.servicebus.message.enqueued_time
New: messaging.batch.message_count
messaging.client_id → messaging.client.id
messaging.consumer_id -> messaging.client.id
messaging.consumer.id	Removed
messaging.conversation_id -> messaging.message.conversation_id
messaging.destination -> messaging.destination.name
messaging.destination_kind	Removed
messaging.destination.kind	Removed
New: messaging.destination.partition.id
messaging.destination_publish.name	Removed
messaging.destination_publish.anonymous	Removed
New: messaging.message.envelope.size
messaging.message_id -> messaging.message.id
messaging.message_payload_compressed_size_bytes	Removed
messaging.message_payload_size_bytes -> messaging.message.body.size
messaging.operation → messaging.operation.type
New: messaging.operation.name
messaging.protocol	Removed
messaging.protocol_version	Removed
messaging.source.kind	Removed
messaging.source.anonymous - messaging.destination.anonymous
messaging.source.name -> messaging.destination.name
messaging.source.template - messaging.destination.template
messaging.source.temporary - messaging.destination.temporary
messaging.temp_destination -> messaging.destination.temporary
messaging.url	Removed
net.app.protocol.name	Removed
net.app.protocol.version	Removed
net.peer.name -> server.address
net.peer.port -> server.port
net.protocol.name	Removed
net.protocol.version	Removed
net.sock.peer.addr	Removed
net.sock.peer.port	Removed
net.sock.family	Removed
network.protocol.name	Removed
network.protocol.version	Removed
network.transport	Removed
network.type	Removed
server.socket.address -> network.peer.address	TODO (removed for most, renamed for rabbit and some others)
server.socket.port -> network.peer.port	TODO (removed for most, renamed for rabbit and some others)
server.socket.domain	Removed

[lmolkova]

Looking into #1090, it's be nice to mention that we renamed spans and defined a bunch of metrics.

[joaopgrassi]

@lmolkova I re-worked the page to provide migrations to the stable version from versions back to 1.16. I think several instrumentations use the old semconv versions so I thought of having this way back further. Took a lot of work, but I think I got everything now :) Everything is mapped in this spreadsheet https://docs.google.com/spreadsheets/d/1evrqe2HfwYbfSfGmXz_O_0iupkFX5lPKrkSBwszfggI/edit?usp=sharing

Please take a look to see what you think. Then I will mention/link to the other changes, like span names, new span structure and metrics.

[lmolkova]

The attribute changes look awesome!
I think we need to mention other changes too.

[lmolkova]

we probably want to mention span name, kind, and metric changes

[joaopgrassi]

I added sections for span name|kind and operation. For metrics, I simply listed the latest "state" as I'm not sure if we should really document all the changes that happened to them.