From e2227c60f8a475c88632303809f15b3acca1adcc Mon Sep 17 00:00:00 2001
From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
Date: Fri, 13 Dec 2024 14:38:11 +0100
Subject: [PATCH] Messaging: Clarify `{destination}` value used on span name
 (#1635)

---
 .chloggen/clarify-temporary-destination.yaml |  5 +++++
 docs/messaging/messaging-spans.md            | 13 +++++++++----
 2 files changed, 14 insertions(+), 4 deletions(-)
 create mode 100644 .chloggen/clarify-temporary-destination.yaml

diff --git a/.chloggen/clarify-temporary-destination.yaml b/.chloggen/clarify-temporary-destination.yaml
new file mode 100644
index 0000000000..fb6d9e52b9
--- /dev/null
+++ b/.chloggen/clarify-temporary-destination.yaml
@@ -0,0 +1,5 @@
+change_type: enhancement
+component: messaging
+note: Further clarify `{destination}` value on span names
+issues: [1635]
+subtext:
diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md
index 73a90bdd81..cda4fcfa54 100644
--- a/docs/messaging/messaging-spans.md
+++ b/docs/messaging/messaging-spans.md
@@ -191,19 +191,24 @@ Messaging spans SHOULD follow the overall [guidelines for span names](https://gi
 
 <!-- markdown-link-check-disable -->
 <!-- HTML anchors are not supported https://github.com/tcort/markdown-link-check/issues/225-->
-The **span name** SHOULD be `{messaging.operation.name} {destination}` (see below for the exact definition of the [`{destination}`](#destination-placeholder) placeholder).
+The **span name** SHOULD be `{messaging.operation.name} {destination}`
+(see below for the exact definition of the [`{destination}`](#destination-placeholder) placeholder).
 <!-- markdown-link-check-enable -->
 
-Semantic conventions for individual messaging systems MAY specify different span name format and then MUST document it in semantic conventions for specific messaging technologies.
+Semantic conventions for individual messaging systems MAY specify different
+span name format and then MUST document it in semantic conventions
+for specific messaging technologies.
 
-The <span id="destination-placeholder">`{destination}`</span> SHOULD describe the entity that the operation is performed against
+The <span id="destination-placeholder">`{destination}`</span>
+SHOULD describe the entity that the operation is performed against
 and SHOULD adhere to one of the following values, provided they are accessible:
 
 1. `messaging.destination.template` SHOULD be used when it is available.
 2. `messaging.destination.name` SHOULD be used when the destination is known to be neither [temporary nor anonymous](#temporary-and-anonymous-destinations).
 3. `server.address:server.port` SHOULD be used only for operations not targeting any specific destination(s).
 
-If a corresponding `{destination}` value is not available for a specific operation, the instrumentation SHOULD omit the `{destination}`.
+If a (low-cardinality) corresponding `{destination}` value is not available for
+a specific operation, the instrumentation SHOULD omit the `{destination}`.
 
 Examples: