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 -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). -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 `{destination}` SHOULD describe the entity that the operation is performed against +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: 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: