review comments and rebase

open-telemetry · Jul 26, 2023 · 454e335 · 454e335
1 parent a5509c6
commit 454e335
Show file tree

Hide file tree

Showing 6 changed files with 451 additions and 32 deletions.
diff --git a/docs/messaging/README.md b/docs/messaging/README.md
@@ -14,6 +14,7 @@ This document defines semantic conventions for messaging systems spans, metrics
 Semantic conventions for messaging systems are defined for the following signals:
 
 * [Messaging Spans](messaging-spans.md): Semantic Conventions for messaging *spans*.
+* [Messaging Metrics](messaging-metrics.md): Semantic Conventions for messaging *metrics*.
 
 Technology specific semantic conventions are defined for the following messaging systems:
 

diff --git a/docs/messaging/messaging-metrics.md b/docs/messaging/messaging-metrics.md
diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md
@@ -1,4 +1,4 @@
-# Messaging Systems
+# Semantic Conventions for Messaging Spans
 
 **Status**: [Experimental][DocumentStatus]
 
@@ -206,7 +206,7 @@ The following operations related to messages are defined for these semantic conv
 
 ## Messaging attributes
 
-<!-- semconv messaging -->
+<!-- semconv messaging(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Required |
@@ -225,9 +225,10 @@ The following operations related to messages are defined for these semantic conv
 | [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [14] | `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 | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. [15] | `example.com` | Conditionally Required: If available. |
+| [`server.address`](../general/attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | Conditionally Required: If available. |
+| [`server.port`](../general/attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Conditionally Required: If available. |
 | [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. |
-| [`server.socket.domain`](../general/attributes.md) | string | The domain name of an immediate peer. [16] | `proxy.example.com` | Recommended: [17] |
+| [`server.socket.domain`](../general/attributes.md) | string | The domain name of an immediate peer. [15] | `proxy.example.com` | Recommended: [16] |
 | [`server.socket.port`](../general/attributes.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. |
 
 **[1]:** If a custom value is used, it MUST be of low cardinality.
@@ -259,11 +260,9 @@ the broker does not have such notion, the destination name SHOULD uniquely ident
 
 **[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`.
 
-**[15]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from.
+**[15]:** Typically observed from the client side, and represents a proxy or other intermediary domain name.
 
-**[16]:** Typically observed from the client side, and represents a proxy or other intermediary domain name.
-
-**[17]:** If different than `server.address` and if `server.socket.address` is set.
+**[16]:** If different than `server.address` and if `server.socket.address` is set.
 
 `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.
 
@@ -272,6 +271,22 @@ the broker does not have such notion, the destination name SHOULD uniquely ident
 | `publish` | publish |
 | `receive` | receive |
 | `process` | process |
+
+`network.transport` 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.
+
+| Value  | Description |
+|---|---|
+| `tcp` | TCP |
+| `udp` | UDP |
+| `pipe` | Named or anonymous pipe. See note below. |
+| `unix` | Unix domain socket |
+
+`network.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.
+
+| Value  | Description |
+|---|---|
+| `ipv4` | IPv4 |
+| `ipv6` | IPv6 |
 <!-- endsemconv -->
 
 Additionally `server.port` from the [network attributes][] is recommended.

diff --git a/docs/system/runtime-environment-metrics.md b/docs/system/runtime-environment-metrics.md
@@ -299,9 +299,7 @@ Note that the JVM does not provide a definition of what "recent" means.
 <!-- semconv metric.process.runtime.jvm.cpu.recent_utilization(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
-| `process.runtime.jvm.cpu.recent_utilization` | Gauge | `1` | Recent CPU utilization for the process as reported by the JVM. [1] |
-
-**[1]:** The value range is [0.0,1.0]. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()).
+| `process.runtime.jvm.cpu.recent_utilization` | Gauge | `1` | Recent CPU utilization for the process as reported by the JVM. |
 <!-- endsemconv -->
 
 <!-- semconv metric.process.runtime.jvm.cpu.recent_utilization(full) -->
@@ -347,9 +345,7 @@ and [`com.ibm.lang.management.OperatingSystemMXBean#getSystemCpuLoad()`](https:/
 <!-- semconv metric.process.runtime.jvm.system.cpu.utilization(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
-| `process.runtime.jvm.system.cpu.utilization` | Gauge | `1` | Recent CPU utilization for the whole system as reported by the JVM. [1] |
-
-**[1]:** The value range is [0.0,1.0]. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getCpuLoad()).
+| `process.runtime.jvm.system.cpu.utilization` | Gauge | `1` | Recent CPU utilization for the whole system as reported by the JVM. |
 <!-- endsemconv -->
 
 <!-- semconv metric.process.runtime.jvm.system.cpu.utilization(full) -->
@@ -363,9 +359,7 @@ This metric is obtained from [`OperatingSystemMXBean#getSystemLoadAverage()`](ht
 <!-- semconv metric.process.runtime.jvm.system.cpu.load_1m(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
-| `process.runtime.jvm.system.cpu.load_1m` | Gauge | `{run_queue_item}` | Average CPU load of the whole system for the last minute as reported by the JVM. [1] |
-
-**[1]:** The value range is [0,n], where n is the number of CPU cores - or a negative number if the value is not available. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/java.management/java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage()).
+| `process.runtime.jvm.system.cpu.load_1m` | Gauge | `{run_queue_item}` | Average CPU load of the whole system for the last minute as reported by the JVM. |
 <!-- endsemconv -->
 
 <!-- semconv metric.process.runtime.jvm.system.cpu.load_1m(full) -->

diff --git a/model/metrics/messaging.yaml b/model/metrics/messaging.yaml
@@ -0,0 +1,88 @@
+groups:
+  - id: metric.messaging.attributes
+    type: attribute_group
+    brief: "Common messaging metrics attributes."
+    extends: messaging.attributes.common
+    attributes:
+      - ref: messaging.destination.name
+        requirement_level:
+          conditionally_required: if and only if `messaging.destination.name` is known to have low cardinality. Otherwise, `messaging.destination.template` MAY be populated.
+      - ref: messaging.destination.template
+        requirement_level:
+          conditionally_required: if available.
+      - id: messaging.todo.status
+        type: string
+        brief: "The status of the operation: TODO"
+        requirement_level: required
+        examples: ["ok", "error", "timeout"]
+
+  # durations
+  - id: metric.messaging.publish.duration
+    type: metric
+    metric_name: messaging.publish.duration
+    brief: "Measures the duration of publish operation."
+    instrument: histogram
+    unit: "s"
+    extends: metric.messaging.attributes
+
+  - id: metric.messaging.receive.duration
+    type: metric
+    metric_name: messaging.receive.duration
+    brief: "Measures the duration of receive operation."
+    instrument: histogram
+    unit: "s"
+    extends: metric.messaging.attributes
+
+  - id: metric.messaging.deliver.duration
+    type: metric
+    metric_name: messaging.deliver.duration
+    brief: "Measures the duration of deliver operation."
+    instrument: histogram
+    unit: "s"
+    extends: metric.messaging.attributes
+
+  - id: metric.messaging.settle.duration
+    type: metric
+    metric_name: messaging.settle.duration
+    brief: "Measures the duration of settle operation."
+    instrument: histogram
+    unit: "s"
+    extends: metric.messaging.attributes
+    attributes:
+      - id: messaging.todo_settlement.status
+        type: string
+        brief: "The status of the settlement: acknowledged, rejected, TODO"
+        examples: ["ack", "nack"]
+
+  # counters
+  - id: metric.messaging.publish.messages
+    type: metric
+    metric_name: messaging.publish.messages
+    brief: "Measures the number of published messages."
+    instrument: counter
+    unit: "message"
+    extends: metric.messaging.attributes
+
+  - id: metric.messaging.receive.messages
+    type: metric
+    metric_name: messaging.receive.messages
+    brief: "Measures the number of received messages."
+    instrument: counter
+    unit: "message"
+    extends: metric.messaging.attributes
+
+  - id: metric.messaging.deliver.messages
+    type: metric
+    metric_name: messaging.deliver.messages
+    brief: "Measures the number of delivered messages."
+    instrument: counter
+    unit: "message"
+    extends: metric.messaging.attributes
+
+  - id: metric.messaging.settle.messages
+    type: metric
+    metric_name: messaging.settle.messages
+    brief: "Measures the number of settled messages."
+    instrument: counter
+    unit: "message"
+    extends: metric.messaging.attributes
diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml
@@ -64,18 +64,36 @@ groups:
         type: boolean
         brief: 'A boolean that is true if the message destination is anonymous (could be unnamed or have auto-generated name).'
 
-  - id: messaging
+  - id: messaging.attributes.common
+    type: attribute_group
+    brief: "Common messaging attributes."
     prefix: messaging
-    type: span
-    brief: >
-        This document defines general attributes used in
-        messaging systems.
     attributes:
       - id: system
         type: string
         requirement_level: required
         brief: 'A string identifying the messaging system.'
         examples: ['kafka', 'rabbitmq', 'rocketmq', 'activemq', 'AmazonSQS']
+      - ref: server.address
+        requirement_level:
+          conditionally_required: If available.
+      - ref: server.port
+        requirement_level:
+          conditionally_required: If available.
+      - ref: server.socket.address
+        tag: connection-level
+      - ref: network.protocol.name
+        examples: ['amqp', 'mqtt']
+      - ref: network.protocol.version
+
+  - id: messaging
+    prefix: messaging
+    type: span
+    brief: >
+        This document defines general attributes used in
+        messaging systems.
+    extends: messaging.attributes.common
+    attributes:
       - id: operation
         type:
           allow_custom_values: true
@@ -134,13 +152,6 @@ groups:
       - ref: messaging.message.payload_compressed_size_bytes
         requirement_level:
           recommended: Only if span represents operation on a single message.
-      - ref: server.address
-        note: >
-          This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from.
-        requirement_level:
-          conditionally_required: If available.
-      - ref: server.socket.address
-        tag: connection-level
       - ref: server.socket.port
         tag: connection-level
       - ref: network.transport
@@ -151,9 +162,6 @@ groups:
         tag: connection-level
         requirement_level:
           recommended: If different than `server.address` and if `server.socket.address` is set.
-      - ref: network.protocol.name
-        examples: ['amqp', 'mqtt']
-      - ref: network.protocol.version
 
   - id: messaging.rabbitmq
     prefix: messaging.rabbitmq