Move streaming note to notes section

open-telemetry · Aug 21, 2023 · ef58a16 · ef58a16
1 parent 99f3f9d
commit ef58a16
Show file tree

Hide file tree

Showing 3 changed files with 78 additions and 40 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -57,6 +57,8 @@ release.
   ([#60](https://github.com/open-telemetry/semantic-conventions/pull/60))
 - BREAKING: Remove pluralization from JVM metric namespaces.
   ([#252](https://github.com/open-telemetry/semantic-conventions/pull/252))
+- BREAKING: Moved RPC streaming notes from metric brief section to notes section.
+  ([#275](https://github.com/open-telemetry/semantic-conventions/pull/275))
 
 ## v1.21.0 (2023-07-13)
 

diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md
@@ -79,10 +79,12 @@ This metric is [recommended][MetricRecommended].
 <!-- semconv metric.rpc.server.duration(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
-| `rpc.server.duration` | Histogram | `ms` | Measures the duration of inbound RPC. **Streaming**: N/A. [1] |
+| `rpc.server.duration` | Histogram | `ms` | Measures the duration of inbound RPC. [1] |
 
 **[1]:** While streaming RPCs may record this metric as start-of-batch
 to end-of-batch, it's hard to interpret in practice.
+
+**Streaming**: N/A.
 <!-- endsemconv -->
 
 #### Metric: `rpc.server.request.size`
@@ -92,7 +94,9 @@ This metric is [recommended][MetricRecommended].
 <!-- semconv metric.rpc.server.request.size(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
-| `rpc.server.request.size` | Histogram | `By` | Measures the size of RPC request messages (uncompressed). **Streaming**: Recorded per message in a streaming batch |
+| `rpc.server.request.size` | Histogram | `By` | Measures the size of RPC request messages (uncompressed). [1] |
+
+**[1]:** **Streaming**: Recorded per message in a streaming batch
 <!-- endsemconv -->
 
 #### Metric: `rpc.server.response.size`
@@ -102,7 +106,9 @@ This metric is [recommended][MetricRecommended].
 <!-- semconv metric.rpc.server.response.size(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
-| `rpc.server.response.size` | Histogram | `By` | Measures the size of RPC response messages (uncompressed). **Streaming**: Recorded per response in a streaming batch |
+| `rpc.server.response.size` | Histogram | `By` | Measures the size of RPC response messages (uncompressed). [1] |
+
+**[1]:** **Streaming**: Recorded per response in a streaming batch
 <!-- endsemconv -->
 
 #### Metric: `rpc.server.requests_per_rpc`
@@ -112,7 +118,11 @@ This metric is [recommended][MetricRecommended].
 <!-- semconv metric.rpc.server.requests_per_rpc(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
-| `rpc.server.requests_per_rpc` | Histogram | `{count}` | Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs. **Streaming**: This metric is required for server and client streaming RPCs |
+| `rpc.server.requests_per_rpc` | Histogram | `{count}` | Measures the number of messages received per RPC. [1] |
+
+**[1]:** Should be 1 for all non-streaming RPCs.
+
+**Streaming** : This metric is required for server and client streaming RPCs
 <!-- endsemconv -->
 
 #### Metric: `rpc.server.responses_per_rpc`
@@ -122,7 +132,11 @@ This metric is [recommended][MetricRecommended].
 <!-- semconv metric.rpc.server.responses_per_rpc(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
-| `rpc.server.responses_per_rpc` | Histogram | `{count}` | Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs. **Streaming**: This metric is required for server and client streaming RPCs |
+| `rpc.server.responses_per_rpc` | Histogram | `{count}` | Measures the number of messages sent per RPC. [1] |
+
+**[1]:** Should be 1 for all non-streaming RPCs.
+
+**Streaming**: This metric is required for server and client streaming RPCs
 <!-- endsemconv -->
 
 ### RPC Client
@@ -137,10 +151,12 @@ This metric is [recommended][MetricRecommended].
 <!-- semconv metric.rpc.client.duration(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
-| `rpc.client.duration` | Histogram | `ms` | Measures the duration of outbound RPC **Streaming**: N/A. [1] |
+| `rpc.client.duration` | Histogram | `ms` | Measures the duration of outbound RPC. [1] |
 
 **[1]:** While streaming RPCs may record this metric as start-of-batch
 to end-of-batch, it's hard to interpret in practice.
+
+**Streaming**: N/A.
 <!-- endsemconv -->
 
 #### Metric: `rpc.client.request.size`
@@ -150,7 +166,9 @@ This metric is [recommended][MetricRecommended].
 <!-- semconv metric.rpc.client.request.size(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
-| `rpc.client.request.size` | Histogram | `By` | Measures the size of RPC request messages (uncompressed). **Streaming**: Recorded per message in a streaming batch |
+| `rpc.client.request.size` | Histogram | `By` | Measures the size of RPC request messages (uncompressed). [1] |
+
+**[1]:** **Streaming**: Recorded per message in a streaming batch
 <!-- endsemconv -->
 
 #### Metric: `rpc.client.response.size`
@@ -160,7 +178,9 @@ This metric is [recommended][MetricRecommended].
 <!-- semconv metric.rpc.client.response.size(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
-| `rpc.client.response.size` | Histogram | `By` | Measures the size of RPC response messages (uncompressed). **Streaming**: Recorded per response in a streaming batch |
+| `rpc.client.response.size` | Histogram | `By` | Measures the size of RPC response messages (uncompressed). [1] |
+
+**[1]:** **Streaming**: Recorded per response in a streaming batch
 <!-- endsemconv -->
 
 #### Metric: `rpc.client.requests_per_rpc`
@@ -170,7 +190,11 @@ This metric is [recommended][MetricRecommended].
 <!-- semconv metric.rpc.client.requests_per_rpc(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
-| `rpc.client.requests_per_rpc` | Histogram | `{count}` | Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs. **Streaming**: This metric is required for server and client streaming RPCs |
+| `rpc.client.requests_per_rpc` | Histogram | `{count}` | Measures the number of messages received per RPC. [1] |
+
+**[1]:** Should be 1 for all non-streaming RPCs.
+
+**Streaming**: This metric is required for server and client streaming RPCs
 <!-- endsemconv -->
 
 #### Metric: `rpc.client.responses_per_rpc`
@@ -180,7 +204,11 @@ This metric is [recommended][MetricRecommended].
 <!-- semconv metric.rpc.client.responses_per_rpc(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
-| `rpc.client.responses_per_rpc` | Histogram | `{count}` | Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs. **Streaming**: This metric is required for server and client streaming RPCs |
+| `rpc.client.responses_per_rpc` | Histogram | `{count}` | Measures the number of messages sent per RPC. [1] |
+
+**[1]:** Should be 1 for all non-streaming RPCs.
+
+**Streaming**: This metric is required for server and client streaming RPCs
 <!-- endsemconv -->
 
 ## Attributes

diff --git a/model/metrics/rpc-metrics.yaml b/model/metrics/rpc-metrics.yaml
@@ -20,96 +20,104 @@ groups:
   - id: metric.rpc.server.duration
     type: metric
     metric_name: rpc.server.duration
-    brief: >
-      Measures the duration of inbound RPC.
-      **Streaming**: N/A.
+    brief: Measures the duration of inbound RPC.
     instrument: histogram
     unit: "ms"
     note: |
       While streaming RPCs may record this metric as start-of-batch
       to end-of-batch, it's hard to interpret in practice.
 
+      **Streaming**: N/A.
+
   - id: metric.rpc.server.request.size
     type: metric
     metric_name: rpc.server.request.size
-    brief: >
-      Measures the size of RPC request messages (uncompressed).
-      **Streaming**: Recorded per message in a streaming batch
+    brief: Measures the size of RPC request messages (uncompressed).
     instrument: histogram
     unit: "By"
+    note: |
+      **Streaming**: Recorded per message in a streaming batch
 
   - id: metric.rpc.server.response.size
     type: metric
     metric_name: rpc.server.response.size
-    brief: >
-      Measures the size of RPC response messages (uncompressed).
-      **Streaming**: Recorded per response in a streaming batch
+    brief: Measures the size of RPC response messages (uncompressed).
     instrument: histogram
     unit: "By"
+    note: |
+      **Streaming**: Recorded per response in a streaming batch
 
   - id: metric.rpc.server.requests_per_rpc
     type: metric
     metric_name: rpc.server.requests_per_rpc
-    brief: >
-      Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs.
-      **Streaming**: This metric is required for server and client streaming RPCs
+    brief: Measures the number of messages received per RPC.
     instrument: histogram
     unit: "{count}"
+    note: |
+      Should be 1 for all non-streaming RPCs.
+
+      **Streaming** : This metric is required for server and client streaming RPCs
 
   - id: metric.rpc.server.responses_per_rpc
     type: metric
     metric_name: rpc.server.responses_per_rpc
-    brief: >
-      Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs.
-      **Streaming**: This metric is required for server and client streaming RPCs
+    brief: Measures the number of messages sent per RPC.
     instrument: histogram
     unit: "{count}"
+    note: |
+      Should be 1 for all non-streaming RPCs.
+
+      **Streaming**: This metric is required for server and client streaming RPCs
 
   # RPC Client metrics
   - id: metric.rpc.client.duration
     type: metric
     metric_name: rpc.client.duration
-    brief: >
-      Measures the duration of outbound RPC
-      **Streaming**: N/A.
+    brief: Measures the duration of outbound RPC.
     instrument: histogram
     unit: "ms"
     note: |
       While streaming RPCs may record this metric as start-of-batch
       to end-of-batch, it's hard to interpret in practice.
 
+      **Streaming**: N/A.
+
   - id: metric.rpc.client.request.size
     type: metric
     metric_name: rpc.client.request.size
-    brief: >
-      Measures the size of RPC request messages (uncompressed).
-      **Streaming**: Recorded per message in a streaming batch
+    brief: Measures the size of RPC request messages (uncompressed).
     instrument: histogram
     unit: "By"
+    note: |
+      **Streaming**: Recorded per message in a streaming batch
 
   - id: metric.rpc.client.response.size
     type: metric
     metric_name: rpc.client.response.size
-    brief: >
-      Measures the size of RPC response messages (uncompressed).
-      **Streaming**: Recorded per response in a streaming batch
+    brief: Measures the size of RPC response messages (uncompressed).
     instrument: histogram
     unit: "By"
+    note: |
+      **Streaming**: Recorded per response in a streaming batch
 
   - id: metric.rpc.client.requests_per_rpc
     type: metric
     metric_name: rpc.client.requests_per_rpc
-    brief: >
-      Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs.
-      **Streaming**: This metric is required for server and client streaming RPCs
+    brief: Measures the number of messages received per RPC.
     instrument: histogram
     unit: "{count}"
+    note: |
+      Should be 1 for all non-streaming RPCs.
+
+      **Streaming**: This metric is required for server and client streaming RPCs
 
   - id: metric.rpc.client.responses_per_rpc
     type: metric
     metric_name: rpc.client.responses_per_rpc
-    brief: >
-      Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs.
-      **Streaming**: This metric is required for server and client streaming RPCs
+    brief: Measures the number of messages sent per RPC.
     instrument: histogram
     unit: "{count}"
+    note: |
+      Should be 1 for all non-streaming RPCs.
+
+      **Streaming**: This metric is required for server and client streaming RPCs