From e880bddb63437119a33caddd643e069b500851a6 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Wed, 13 Sep 2023 13:11:19 +0200 Subject: [PATCH 1/3] Fix System metrics yaml warning (#322) --- model/metrics/system-metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml index 41c508f3d2..2759d1f66f 100644 --- a/model/metrics/system-metrics.yaml +++ b/model/metrics/system-metrics.yaml @@ -452,7 +452,7 @@ groups: - ref: system.network.state - ref: network.transport - # system.processes.* metrics and attribute group + # system.processes.* metrics and attribute group - id: attributes.system.processes prefix: system.processes type: attribute_group From 875cfefe7d143aca5258c625c98d87d3c95aba46 Mon Sep 17 00:00:00 2001 From: Tyler Helmuth <12352919+TylerHelmuth@users.noreply.github.com> Date: Mon, 18 Sep 2023 09:44:11 -0600 Subject: [PATCH 2/3] Reduce restrictions on which metrics may be named utilization (#280) --- docs/general/metrics.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 938a5e73e1..c4c6398fbf 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -166,8 +166,10 @@ over all attribute values SHOULD be equal to the **limit**. - **utilization** - an instrument that measures the *fraction* of **usage** out of its **limit** should be called `entity.utilization`. For example, -`system.memory.utilization` for the fraction of memory in use. Utilization -values are in the range `[0, 1]`. +`system.memory.utilization` for the fraction of memory in use. Utilization can +be with respect to a fixed limit or a soft limit. Utilization values are +represended as a ratio and are typically in the range `[0, 1]`, but may go above 1 +in case of exceeding a soft limit. - **time** - an instrument that measures passage of time should be called `entity.time`. For example, `system.cpu.time` with attribute `state = idle | user From a5979b01bd4549da6868bc8c97bf5a904f154be0 Mon Sep 17 00:00:00 2001 From: Johannes Tax Date: Tue, 19 Sep 2023 12:37:12 +0200 Subject: [PATCH 3/3] Make messaging payload attributes consistent with other conventions (#229) Co-authored-by: Alexander Wert Co-authored-by: Joao Grassi --- CHANGELOG.md | 3 +++ docs/messaging/messaging-spans.md | 44 ++++++++++++++++++------------- model/trace/messaging.yaml | 22 ++++++++++------ schema-next.yaml | 4 +++ 4 files changed, 46 insertions(+), 27 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 96acda87f4..4d6974e789 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -100,6 +100,9 @@ release. - `state` to `system.network.state` - Rename attributes for `system.processes.*` metrics: - `status` to `system.processes.status` +- BREAKING: Rename `messaging.message.payload_size_bytes` to `messaging.message.body.size`, + remove `messaging.message.payload_compressed_size_bytes`. + ([#229](https://github.com/open-telemetry/semantic-conventions/pull/229)) ## v1.21.0 (2023-07-13) diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index c1814ad8d9..6135222dc0 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -66,7 +66,7 @@ Although messaging systems are not as standardized as, e.g., HTTP, it is assumed that the following definitions are applicable to most of them that have similar concepts at all (names borrowed mostly from JMS): -A *message* is an envelope with a potentially empty payload. +A *message* is an envelope with a potentially empty body. This envelope may offer the possibility to convey additional metadata, often in key/value form. A message is sent by a message *producer* to: @@ -225,18 +225,18 @@ The following operations related to messages are defined for these semantic conv | `messaging.destination.name` | string | The message destination name [5] | `MyQueue`; `MyTopic` | Conditionally Required: [6] | | `messaging.destination.template` | string | Low cardinality representation of the messaging destination name [7] | `/customers/{customerId}` | Conditionally Required: [8] | | `messaging.destination.temporary` | boolean | A boolean that is true if the message destination is temporary and might not exist anymore after messages are processed. | | Conditionally Required: [9] | -| `messaging.message.conversation_id` | string | The [conversation ID](#conversations) identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | Recommended: [10] | -| `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [11] | -| `messaging.message.payload_compressed_size_bytes` | int | The compressed size of the message payload in bytes. | `2048` | Recommended: [12] | -| `messaging.message.payload_size_bytes` | int | The (uncompressed) size of the message payload in bytes. Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. | `2738` | Recommended: [13] | +| `messaging.message.body.size` | int | The size of the message body in bytes. [10] | `1439` | Recommended: [11] | +| `messaging.message.conversation_id` | string | The [conversation ID](#conversations) identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | Recommended: [12] | +| `messaging.message.envelope.size` | int | The size of the message body and metadata in bytes. [13] | `2738` | Recommended: [14] | +| `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [15] | | [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `mqtt` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [14] | `3.1.1` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [16] | `3.1.1` | Recommended | | [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | | [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [15] | `example.com` | Conditionally Required: If available. | -| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [16] | `10.5.3.2` | Recommended: If different than `server.address`. | -| [`server.socket.domain`](../general/attributes.md) | string | Immediate server peer's domain name if available without reverse DNS lookup [17] | `proxy.example.com` | Recommended: [18] | -| [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [19] | `16456` | Recommended: If different than `server.port`. | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [17] | `example.com` | Conditionally Required: If available. | +| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [18] | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`server.socket.domain`](../general/attributes.md) | string | Immediate server peer's domain name if available without reverse DNS lookup [19] | `proxy.example.com` | Recommended: [20] | +| [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [21] | `16456` | Recommended: If different than `server.port`. | **[1]:** If a custom value is used, it MUST be of low cardinality. @@ -257,26 +257,32 @@ the broker does not have such notion, the destination name SHOULD uniquely ident **[9]:** If value is `true`. When missing, the value is assumed to be `false`. -**[10]:** Only if span represents operation on a single message. +**[10]:** This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed +body size should be used. -**[11]:** Only for spans that represent an operation on a single message. +**[11]:** Only if span represents operation on a single message. **[12]:** Only if span represents operation on a single message. -**[13]:** Only if span represents operation on a single message. +**[13]:** This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed +size should be used. -**[14]:** `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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. +**[14]:** Only if span represents operation on a single message. -**[15]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. +**[15]:** Only for spans that represent an operation on a single message. -**[16]:** When observed from the client side, this SHOULD represent the immediate server peer address. +**[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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[17]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. + +**[18]:** When observed from the client side, this SHOULD represent the immediate server peer address. When observed from the server side, this SHOULD represent the physical server address. -**[17]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. +**[19]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. -**[18]:** If different than `server.address` and if `server.socket.address` is set. +**[20]:** If different than `server.address` and if `server.socket.address` is set. -**[19]:** When observed from the client side, this SHOULD represent the immediate server peer port. +**[21]:** When observed from the client side, this SHOULD represent the immediate server peer port. When observed from the server side, this SHOULD represent the physical server port. `messaging.operation` 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. diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index bb7a768638..19c8f375ed 100644 --- a/model/trace/messaging.yaml +++ b/model/trace/messaging.yaml @@ -15,16 +15,22 @@ groups: The [conversation ID](#conversations) identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". examples: 'MyConversationId' - - id: message.payload_size_bytes + - id: message.envelope.size type: int brief: > - The (uncompressed) size of the message payload in bytes. - Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. + The size of the message body and metadata in bytes. + note: | + This can refer to both the compressed or uncompressed size. If both sizes are known, the uncompressed + size should be used. examples: 2738 - - id: message.payload_compressed_size_bytes + - id: message.body.size type: int - brief: 'The compressed size of the message payload in bytes.' - examples: 2048 + brief: > + The size of the message body in bytes. + note: | + This can refer to both the compressed or uncompressed body size. If both sizes are known, the uncompressed + body size should be used. + examples: 1439 - id: messaging.destination prefix: messaging.destination @@ -156,10 +162,10 @@ groups: - ref: messaging.message.conversation_id requirement_level: recommended: Only if span represents operation on a single message. - - ref: messaging.message.payload_size_bytes + - ref: messaging.message.envelope.size requirement_level: recommended: Only if span represents operation on a single message. - - ref: messaging.message.payload_compressed_size_bytes + - ref: messaging.message.body.size requirement_level: recommended: Only if span represents operation on a single message. - ref: server.address diff --git a/schema-next.yaml b/schema-next.yaml index 609605b787..7e82205757 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -4,6 +4,10 @@ versions: next: metrics: changes: + # https://github.com/open-telemetry/semantic-conventions/pull/229 + - rename_attributes: + attribute_map: + messaging.message.payload_size_bytes: messaging.message.body.size # https://github.com/open-telemetry/semantic-conventions/pull/224 - rename_metrics: http.client.duration: http.client.request.duration