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

Make `network.protocol.name` conditionally required for messaging (#644) 

Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com>
Co-authored-by: Joao Grassi <joao.grassi@dynatrace.com>
This commit is contained in:
Johannes Tax 2024-01-24 15:57:19 +01:00 committed by GitHub
parent c3e35ee7c7
commit dd41eac32f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 26 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG.md
View File

@ -13,6 +13,8 @@ release.
([#484](https://github.com/open-telemetry/semantic-conventions/pull/484)) ([#484](https://github.com/open-telemetry/semantic-conventions/pull/484))
- Depluralize labels for pod (`k8s.pod.labels.*`) and container (`container.labels.*`) resources - Depluralize labels for pod (`k8s.pod.labels.*`) and container (`container.labels.*`) resources
([#625](https://github.com/open-telemetry/semantic-conventions/pull/625)) ([#625](https://github.com/open-telemetry/semantic-conventions/pull/625))
- Make `network.protocol.name` conditionally required for messaging
([#644](https://github.com/open-telemetry/semantic-conventions/pull/644))
- BREAKING: Generate process metrics from YAML - BREAKING: Generate process metrics from YAML
([#330](https://github.com/open-telemetry/semantic-conventions/pull/330)) ([#330](https://github.com/open-telemetry/semantic-conventions/pull/330))
- Rename `process.threads` to `process.thread.count` - Rename `process.threads` to `process.thread.count`

16
docs/messaging/messaging-metrics.md
View File

@ -29,10 +29,10 @@ All messaging metrics share the same set of attributes:
| [`messaging.destination.name`](../attributes-registry/messaging.md) | string | The message destination name [3] | `MyQueue`; `MyTopic` | Conditionally Required: [4] | | [`messaging.destination.name`](../attributes-registry/messaging.md) | string | The message destination name [3] | `MyQueue`; `MyTopic` | Conditionally Required: [4] |
| [`messaging.destination.template`](../attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [5] | `/customers/{customerId}` | Conditionally Required: if available. | | [`messaging.destination.template`](../attributes-registry/messaging.md) | string | Low cardinality representation of the messaging destination name [5] | `/customers/{customerId}` | Conditionally Required: if available. |
| [`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.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [6] | `amqp`; `mqtt` | Recommended | | [`network.protocol.name`](../attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [6] | `amqp`; `mqtt` | Conditionally Required: [7] |
| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [7] | `3.1.1` | Recommended | | [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [8] | `3.1.1` | 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. [8] | `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. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. |
| [`server.port`](../attributes-registry/server.md) | int | Server port number. [9] | `80`; `8080`; `443` | Recommended | | [`server.port`](../attributes-registry/server.md) | int | Server port number. [10] | `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.
@ -61,11 +61,13 @@ the broker doesn't have such notion, the destination name SHOULD uniquely identi
**[6]:** The value SHOULD be normalized to lowercase. **[6]:** The value SHOULD be normalized to lowercase.
**[7]:** `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`. **[7]:** Only for messaging systems and frameworks that support more than one protocol.
**[8]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. **[8]:** `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`.
**[9]:** 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. **[9]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from.
**[10]:** 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.

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

@ -302,12 +302,12 @@ as described in [Attributes specific to certain messaging systems](#attributes-s
| [`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. [14] | `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` | Conditionally Required: [15] |
| [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [15] | `3.1.1` | Recommended | | [`network.protocol.version`](../attributes-registry/network.md) | string | Version of the protocol specified in `network.protocol.name`. [16] | `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). [16] | `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). [17] | `tcp`; `udp` | 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 | | [`network.type`](../attributes-registry/network.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [18] | `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. [18] | `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. [19] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. |
| [`server.port`](../attributes-registry/server.md) | int | Server port number. [19] | `80`; `8080`; `443` | Recommended | | [`server.port`](../attributes-registry/server.md) | int | Server port number. [20] | `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.
@ -354,19 +354,21 @@ size should be used.
**[14]:** The value SHOULD be normalized to lowercase. **[14]:** The value SHOULD be normalized to lowercase.
**[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`. **[15]:** Only for messaging systems and frameworks that support more than one protocol.
**[16]:** The value SHOULD be normalized to lowercase. **[16]:** `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`.
**[17]:** 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.
**[17]:** The value SHOULD be normalized to lowercase. **[18]:** The value SHOULD be normalized to lowercase.
**[18]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. **[19]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from.
**[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. **[20]:** 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.

2
model/messaging-common.yaml
View File

@ -18,6 +18,8 @@ groups:
- ref: server.port - ref: server.port
- ref: network.protocol.name - ref: network.protocol.name
examples: ['amqp', 'mqtt'] examples: ['amqp', 'mqtt']
requirement_level:
conditionally_required: Only for messaging systems and frameworks that support more than one protocol.
tag: connection-level tag: connection-level
- ref: network.protocol.version - ref: network.protocol.version
tag: connection-level tag: connection-level