Change rpc.*.duration unit from ms to sec, clarify duration in case of streaming

Author: lmolkova

.chloggen/rpc-duration-seconds.yaml

@@ -0,0 +1,4 @@
+change_type: breaking
+component: rpc
+note: Change RPC duration metrics from milliseconds to seconds, clarify metric and span duration semantics for streaming.
+issues: [383]

docs/rpc/rpc-metrics.md

@@ -67,6 +67,10 @@ Below is a list of RPC server metric instruments.
 
 This metric is [recommended][MetricRecommended].
 
+This metric SHOULD be specified with
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/metrics/api.md#instrument-advisory-parameters)
+of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
+
 <!-- semconv metric.rpc.server.duration -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -76,12 +80,10 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability | Entity Associations |
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
-| `rpc.server.duration` | Histogram | `ms` | Measures the duration of inbound RPC. [1] | ![Development](https://img.shields.io/badge/-development-blue) |  |
-
-**[1]:** While streaming RPCs may record this metric as start-of-batch
-to end-of-batch, it's hard to interpret in practice.
+| `rpc.server.duration` | Histogram | `s` | Measures the duration of inbound remote procedure calls (RPC). [1] | ![Development](https://img.shields.io/badge/-development-blue) |  |
 
-**Streaming**: N/A.
+**[1]:** When this metric is reported alongside an RPC server span, the metric value
+SHOULD be the same as the RPC server span duration.
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
@@ -363,12 +365,15 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
 ### RPC client
 
 Below is a list of RPC client metric instruments.
-These apply to traditional RPC usage, not streaming RPCs.
 
 #### Metric: `rpc.client.duration`
 
 This metric is [recommended][MetricRecommended].
 
+This metric SHOULD be specified with
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/metrics/api.md#instrument-advisory-parameters)
+of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
+
 <!-- semconv metric.rpc.client.duration -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -378,12 +383,10 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability | Entity Associations |
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
-| `rpc.client.duration` | Histogram | `ms` | Measures the duration of outbound RPC. [1] | ![Development](https://img.shields.io/badge/-development-blue) |  |
-
-**[1]:** While streaming RPCs may record this metric as start-of-batch
-to end-of-batch, it's hard to interpret in practice.
+| `rpc.client.duration` | Histogram | `s` | Measures the duration of outbound remote procedure calls (RPC). [1] | ![Development](https://img.shields.io/badge/-development-blue) |  |
 
-**Streaming**: N/A.
+**[1]:** When this metric is reported alongside an RPC client span, the metric value
+SHOULD be the same as the RPC client span duration.
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|

docs/rpc/rpc-spans.md

@@ -97,6 +97,13 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service
 
 This span represents an outgoing Remote Procedure Call (RPC).
 
+RPC client spans SHOULD cover the entire client-side lifecycle of an RPC,
+starting when the RPC is initiated and ending when the response is received
+or the RPC is terminated due to an error or cancellation.
+
+For streaming RPCs, the span covers the full lifetime of the request and/or
+response streams until they are closed or terminated.
+
 **Span name:** refer to the [Span Name](/docs/rpc/rpc-spans.md#span-name) section.
 
 **Span kind** MUST be `CLIENT`.
@@ -221,6 +228,13 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
 
 This span represents an incoming Remote Procedure Call (RPC).
 
+RPC server spans SHOULD cover the entire server-side lifecycle of an RPC,
+starting when the request is received and ending when the response is sent
+or the RPC is terminated due to an error or cancellation.
+
+For streaming RPCs, the span SHOULD cover the full lifetime of the request
+and/or response streams until they are closed or terminated.
+
 **Span name:** refer to the [Span Name](/docs/rpc/rpc-spans.md#span-name) section.
 
 **Span kind** MUST be `SERVER`.

model/rpc/metrics.yaml

@@ -7,14 +7,13 @@ groups:
       code_generation:
         metric_value_type: double
     stability: development
-    brief: Measures the duration of inbound RPC.
+    brief: Measures the duration of inbound remote procedure calls (RPC).
     instrument: histogram
-    unit: "ms"
+    unit: "s"
     note: |
-      While streaming RPCs may record this metric as start-of-batch
-      to end-of-batch, it's hard to interpret in practice.
+      When this metric is reported alongside an RPC server span, the metric value
+      SHOULD be the same as the RPC server span duration.
 
-      **Streaming**: N/A.
     extends: attributes.metrics.rpc.server
 
   - id: metric.rpc.server.request.size
@@ -54,14 +53,12 @@ groups:
       code_generation:
         metric_value_type: double
     stability: development
-    brief: Measures the duration of outbound RPC.
+    brief: Measures the duration of outbound remote procedure calls (RPC).
     instrument: histogram
-    unit: "ms"
+    unit: "s"
     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.
+      When this metric is reported alongside an RPC client span, the metric value
+      SHOULD be the same as the RPC client span duration.
     extends: attributes.metrics.rpc.client
 
   - id: metric.rpc.client.request.size

model/rpc/spans.yaml

@@ -4,6 +4,13 @@ groups:
     stability: development
     brief: This span represents an outgoing Remote Procedure Call (RPC).
     note: |
+      RPC client spans SHOULD cover the entire client-side lifecycle of an RPC,
+      starting when the RPC is initiated and ending when the response is received
+      or the RPC is terminated due to an error or cancellation.
+
+      For streaming RPCs, the span covers the full lifetime of the request and/or
+      response streams until they are closed or terminated.
+
       **Span name:** refer to the [Span Name](/docs/rpc/rpc-spans.md#span-name) section.
 
       **Span kind** MUST be `CLIENT`.
@@ -22,6 +29,13 @@ groups:
     brief: This span represents an incoming Remote Procedure Call (RPC).
     events: [rpc.message]
     note: |
+      RPC server spans SHOULD cover the entire server-side lifecycle of an RPC,
+      starting when the request is received and ending when the response is sent
+      or the RPC is terminated due to an error or cancellation.
+
+      For streaming RPCs, the span SHOULD cover the full lifetime of the request
+      and/or response streams until they are closed or terminated.
+
       **Span name:** refer to the [Span Name](/docs/rpc/rpc-spans.md#span-name) section.
 
       **Span kind** MUST be `SERVER`.