open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Remove obsolete footnotes for messaging attributes (#642) 

Co-authored-by: Joao Grassi <joao.grassi@dynatrace.com>
This commit is contained in:
Johannes Tax 2024-01-17 17:52:22 +01:00 committed by GitHub
parent 50e2eac498
commit bb017fa80a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 32 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
docs/messaging/messaging-spans.md
View File

@ -24,7 +24,6 @@
+ [Producer spans](#producer-spans) + [Producer spans](#producer-spans)
+ [Consumer spans](#consumer-spans) + [Consumer spans](#consumer-spans)
- [Messaging attributes](#messaging-attributes) - [Messaging attributes](#messaging-attributes)
* [Attribute namespaces](#attribute-namespaces)
* [Consumer attributes](#consumer-attributes) * [Consumer attributes](#consumer-attributes)
* [Per-message attributes](#per-message-attributes) * [Per-message attributes](#per-message-attributes)
* [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems) * [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems)
@ -272,6 +271,19 @@ messages were received). For each message it accounts for, the "Deliver" or
## Messaging attributes ## Messaging attributes
Messaging attributes are organized into the following namespaces:
- `messaging.message`: Contains [per-message attributes](#per-message-attributes) that describe individual messages. Those attributes are relevant only for spans or links that represent a single message.
- `messaging.destination`: Contains attributes that describe the logical entity messages are published to. See [Destinations](#destinations) for more details.
- `messaging.destination_publish`: Contains attributes that describe the logical entity messages were originally published to. See [Destinations](#destinations) for more details.
- `messaging.batch`: Contains attributes that describe batch operations.
- `messaging.consumer`: Contains [consumer attributes](#consumer-attributes) that describe the application instance that consumes a message. See [consumer](#consumer) for more details.
The communication with the intermediary is described with general [network attributes].
Messaging system-specific attributes MUST be defined in the corresponding `messaging.{system}` namespace
as described in [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems).
<!-- semconv messaging(full) --> <!-- semconv messaging(full) -->
| Attribute | Type | Description | Examples | Requirement Level | | Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---| |---|---|---|---|---|
@ -282,20 +294,20 @@ messages were received). For each message it accounts for, the "Deliver" or
| [`messaging.destination.name`](../attributes-registry/messaging.md) | string | The message destination name [6] | `MyQueue`; `MyTopic` | Conditionally Required: [7] | | [`messaging.destination.name`](../attributes-registry/messaging.md) | string | The message destination name [6] | `MyQueue`; `MyTopic` | Conditionally Required: [7] |
| [`messaging.destination.template`](../attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [8] | `/customers/{customerId}` | Conditionally Required: [9] | | [`messaging.destination.template`](../attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [8] | `/customers/{customerId}` | Conditionally Required: [9] |
| [`messaging.destination.temporary`](../attributes-registry/messaging.md) | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | Conditionally Required: [10] | | [`messaging.destination.temporary`](../attributes-registry/messaging.md) | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | Conditionally Required: [10] |
| [`messaging.message.body.size`](../attributes-registry/messaging.md) | int | The size of the message body in bytes. [11] | `1439` | Recommended: [12] | | [`messaging.message.body.size`](../attributes-registry/messaging.md) | int | The size of the message body in bytes. [11] | `1439` | Recommended |
| [`messaging.message.conversation_id`](../attributes-registry/messaging.md) | string | The conversation ID identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | Recommended: [13] | | [`messaging.message.conversation_id`](../attributes-registry/messaging.md) | string | The conversation ID identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | Recommended |
| [`messaging.message.envelope.size`](../attributes-registry/messaging.md) | int | The size of the message body and metadata in bytes. [14] | `2738` | Recommended: [15] | | [`messaging.message.envelope.size`](../attributes-registry/messaging.md) | int | The size of the message body and metadata in bytes. [12] | `2738` | Recommended |
| [`messaging.message.id`](../attributes-registry/messaging.md) | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [16] | | [`messaging.message.id`](../attributes-registry/messaging.md) | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended |
| [`messaging.operation`](../attributes-registry/messaging.md) | string | A string identifying the kind of messaging operation. [17] | `publish` | Required | | [`messaging.operation`](../attributes-registry/messaging.md) | string | A string identifying the kind of messaging operation. [13] | `publish` | Required |
| [`messaging.system`](../attributes-registry/messaging.md) | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `activemq` | Required | | [`messaging.system`](../attributes-registry/messaging.md) | string | An identifier for the messaging system being used. See below for a list of well-known identifiers. | `activemq` | Required |
| [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | | [`network.peer.address`](../attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended |
| [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | | [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. |
| [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [18] | `amqp`; `mqtt` | Recommended | | [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [14] | `amqp`; `mqtt` | Recommended |
| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [19] | `3.1.1` | Recommended | | [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [15] | `3.1.1` | Recommended |
| [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [20] | `tcp`; `udp` | Recommended | | [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [16] | `tcp`; `udp` | Recommended |
| [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [21] | `ipv4`; `ipv6` | Recommended | | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [17] | `ipv4`; `ipv6` | Recommended |
| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [22] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. | | [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [18] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. |
| [`server.port`](../attributes-registry/server.md) | int | Server port number. [23] | `80`; `8080`; `443` | Recommended | | [`server.port`](../attributes-registry/server.md) | int | Server port number. [19] | `80`; `8080`; `443` | Recommended |
**[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality. **[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality.
Instrumentations SHOULD document the list of errors they report. Instrumentations SHOULD document the list of errors they report.
@ -335,34 +347,26 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi
**[11]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed **[11]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed
body size should be used. body size should be used.
**[12]:** Only if span represents operation on a single message. **[12]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed
**[13]:** Only if span represents operation on a single message.
**[14]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed
size should be used. size should be used.
**[15]:** Only if span represents operation on a single message. **[13]:** If a custom value is used, it MUST be of low cardinality.
**[16]:** Only for spans that represent an operation on a single message. **[14]:** The value SHOULD be normalized to lowercase.
**[17]:** If a custom value is used, it MUST be of low cardinality. **[15]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
**[18]:** The value SHOULD be normalized to lowercase. **[16]:** The value SHOULD be normalized to lowercase.
**[19]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
**[20]:** The value SHOULD be normalized to lowercase.
Consider always setting the transport when setting a port number, since Consider always setting the transport when setting a port number, since
a port number is ambiguous without knowing the transport. For example a port number is ambiguous without knowing the transport. For example
different processes could be listening on TCP port 12345 and UDP port 12345. different processes could be listening on TCP port 12345 and UDP port 12345.
**[21]:** The value SHOULD be normalized to lowercase. **[17]:** The value SHOULD be normalized to lowercase.
**[22]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. **[18]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from.
**[23]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[19]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.
`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
@ -415,19 +419,6 @@ Additionally `server.port` from the [network attributes][] is recommended.
Furthermore, it is strongly recommended to add the [`network.transport`][] attribute and follow its guidelines, especially for in-process queueing systems (like [Hangfire][], for example). Furthermore, it is strongly recommended to add the [`network.transport`][] attribute and follow its guidelines, especially for in-process queueing systems (like [Hangfire][], for example).
These attributes should be set to the broker to which the message is sent/from which it is received. These attributes should be set to the broker to which the message is sent/from which it is received.
### Attribute namespaces
- `messaging.message`: Contains attributes that describe individual messages
- `messaging.destination`: Contains attributes that describe the logical entity messages are published to. See [Destinations](#destinations) for more details
- `messaging.destination_publish`: Contains attributes that describe the logical entity messages were originally published to. See [Destinations](#destinations) for more details
- `messaging.batch`: Contains attributes that describe batch operations
- `messaging.consumer`: Contains attributes that describe application instance that consumes a message. See [consumer](#consumer) for more details
Communication with broker is described with general [network attributes].
Messaging system-specific attributes MUST be defined in the corresponding `messaging.{system}` namespace
as described in [Attributes specific to certain messaging systems](#attributes-specific-to-certain-messaging-systems).
[network attributes]: /docs/general/attributes.md#server-and-client-attributes [network attributes]: /docs/general/attributes.md#server-and-client-attributes
[`network.transport`]: /docs/general/attributes.md#network-attributes [`network.transport`]: /docs/general/attributes.md#network-attributes
[Hangfire]: https://www.hangfire.io/ [Hangfire]: https://www.hangfire.io/

8
model/trace/messaging.yaml
View File

@ -77,17 +77,9 @@ groups:
requirement_level: requirement_level:
conditionally_required: If value is `true`. When missing, the value is assumed to be `false`. conditionally_required: If value is `true`. When missing, the value is assumed to be `false`.
- ref: messaging.message.id - ref: messaging.message.id
requirement_level:
recommended: Only for spans that represent an operation on a single message.
- ref: messaging.message.conversation_id - ref: messaging.message.conversation_id
requirement_level:
recommended: Only if span represents operation on a single message.
- ref: messaging.message.envelope.size - ref: messaging.message.envelope.size
requirement_level:
recommended: Only if span represents operation on a single message.
- ref: messaging.message.body.size - ref: messaging.message.body.size
requirement_level:
recommended: Only if span represents operation on a single message.
- ref: server.address - ref: server.address
- ref: network.peer.address - ref: network.peer.address
tag: connection-level tag: connection-level