diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index aaa3647ad3..98d444be96 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -18,7 +18,17 @@ metrics can be filtered for finer grain analysis. - [Metric instruments](#metric-instruments) * [RPC Server](#rpc-server) + + [Metric: `rpc.server.duration`](#metric-rpcserverduration) + + [Metric: `rpc.server.request.size`](#metric-rpcserverrequestsize) + + [Metric: `rpc.server.response.size`](#metric-rpcserverresponsesize) + + [Metric: `rpc.server.requests_per_rpc`](#metric-rpcserverrequests_per_rpc) + + [Metric: `rpc.server.responses_per_rpc`](#metric-rpcserverresponses_per_rpc) * [RPC Client](#rpc-client) + + [Metric: `rpc.client.duration`](#metric-rpcclientduration) + + [Metric: `rpc.client.request.size`](#metric-rpcclientrequestsize) + + [Metric: `rpc.client.response.size`](#metric-rpcclientresponsesize) + + [Metric: `rpc.client.requests_per_rpc`](#metric-rpcclientrequests_per_rpc) + + [Metric: `rpc.client.responses_per_rpc`](#metric-rpcclientresponses_per_rpc) - [Attributes](#attributes) * [Service name](#service-name) - [Semantic Conventions for specific RPC technologies](#semantic-conventions-for-specific-rpc-technologies) @@ -59,28 +69,118 @@ MUST be of the specified type and units. ### RPC Server -Below is a table of RPC server metric instruments. +Below is a list of RPC server metric instruments. -| Name | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | Status | Streaming | -|------|------------|------|-------------------------------------------|-------------|--------|-----------| -| `rpc.server.duration` | Histogram | milliseconds | `ms` | measures duration of inbound RPC | Recommended | N/A. While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. | -| `rpc.server.request.size` | Histogram | Bytes | `By` | measures size of RPC request messages (uncompressed) | Optional | Recorded per message in a streaming batch | -| `rpc.server.response.size` | Histogram | Bytes | `By` | measures size of RPC response messages (uncompressed) | Optional | Recorded per response in a streaming batch | -| `rpc.server.requests_per_rpc` | Histogram | count | `{count}` | measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs | Optional | Required | -| `rpc.server.responses_per_rpc` | Histogram | count | `{count}` | measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs | Optional | Required | +#### Metric: `rpc.server.duration` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `rpc.server.duration` | Histogram | `ms` | Measures the duration of inbound RPC. **Streaming**: N/A. [1] | + +**[1]:** While streaming RPCs may record this metric as start-of-batch +to end-of-batch, it's hard to interpret in practice. + + +#### Metric: `rpc.server.request.size` + +This metric is [recommended][MetricRecommended]. + + +| 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 | + + +#### Metric: `rpc.server.response.size` + +This metric is [recommended][MetricRecommended]. + + +| 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 | + + +#### Metric: `rpc.server.requests_per_rpc` + +This metric is [recommended][MetricRecommended]. + + +| 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 | + + +#### Metric: `rpc.server.responses_per_rpc` + +This metric is [recommended][MetricRecommended]. + + +| 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 Client -Below is a table of RPC client metric instruments. These apply to traditional -RPC usage, not streaming RPCs. +Below is a list of RPC client metric instruments. +These apply to traditional RPC usage, not streaming RPCs. -| Name | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.md#instrument-units)) | Description | Status | Streaming | -|------|------------|------|-------------------------------------------|-------------|--------|-----------| -| `rpc.client.duration` | Histogram | milliseconds | `ms` | measures duration of outbound RPC | Recommended | N/A. While streaming RPCs may record this metric as start-of-batch to end-of-batch, it's hard to interpret in practice. | -| `rpc.client.request.size` | Histogram | Bytes | `By` | measures size of RPC request messages (uncompressed) | Optional | Recorded per message in a streaming batch | -| `rpc.client.response.size` | Histogram | Bytes | `By` | measures size of RPC response messages (uncompressed) | Optional | Recorded per message in a streaming batch | -| `rpc.client.requests_per_rpc` | Histogram | count | `{count}` | measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs | Optional | Required | -| `rpc.client.responses_per_rpc` | Histogram | count | `{count}` | measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs | Optional | Required | +#### Metric: `rpc.client.duration` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `rpc.client.duration` | Histogram | `ms` | Measures the duration of outbound RPC **Streaming**: N/A. [1] | + +**[1]:** While streaming RPCs may record this metric as start-of-batch +to end-of-batch, it's hard to interpret in practice. + + +#### Metric: `rpc.client.request.size` + +This metric is [recommended][MetricRecommended]. + + +| 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 | + + +#### Metric: `rpc.client.response.size` + +This metric is [recommended][MetricRecommended]. + + +| 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 | + + +#### Metric: `rpc.client.requests_per_rpc` + +This metric is [recommended][MetricRecommended]. + + +| 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 | + + +#### Metric: `rpc.client.responses_per_rpc` + +This metric is [recommended][MetricRecommended]. + + +| 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 | + ## Attributes @@ -146,4 +246,5 @@ More specific Semantic Conventions are defined for the following RPC technologie * [gRPC](grpc.md): Semantic Conventions for *gRPC*. * [JSON-RPC](json-rpc.md): Semantic Conventions for *JSON-RPC*. -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.22.0/specification/document-status.md +[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.22.0/specification/metrics/metric-requirement-level.md#recommended diff --git a/model/metrics/rpc-metrics.yaml b/model/metrics/rpc-metrics.yaml new file mode 100644 index 0000000000..38755d4bf2 --- /dev/null +++ b/model/metrics/rpc-metrics.yaml @@ -0,0 +1,115 @@ +groups: + # TODO: Should we list the attributes on each metric + # OR leave a single table like it is today? Since all attributes are applied + # to all metrics, the repetition of them bloats the page + - id: attributes.metrics.rpc + type: attribute_group + brief: "Describes RPC metric attributes." + attributes: + - ref: rpc.system + - ref: rpc.service + - ref: rpc.method + - ref: network.transport + - ref: network.type + - ref: server.address + - ref: server.port + - ref: server.socket.address + - ref: server.socket.port + + # RPC Server metrics + - id: metric.rpc.server.duration + type: metric + metric_name: rpc.server.duration + brief: > + Measures the duration of inbound RPC. + **Streaming**: N/A. + 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. + + - 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 + instrument: histogram + unit: "By" + + - 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 + instrument: histogram + unit: "By" + + - 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 + instrument: histogram + unit: "{count}" + + - 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 + instrument: histogram + unit: "{count}" + + # 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. + 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. + + - 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 + instrument: histogram + unit: "By" + + - 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 + instrument: histogram + unit: "By" + + - 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 + instrument: histogram + unit: "{count}" + + - 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 + instrument: histogram + unit: "{count}"