From 9c094b7df1675752b5091392f04634d602985b98 Mon Sep 17 00:00:00 2001 From: liudmila molkova Date: Sat, 10 Jan 2026 12:04:02 -0800 Subject: [PATCH 1/4] Deprecate rpc.client|server.request|response.size metrics --- docs/rpc/rpc-metrics.md | 484 ------------------- model/rpc/deprecated/metrics-deprecated.yaml | 69 +++ model/rpc/metrics.yaml | 56 --- 3 files changed, 69 insertions(+), 540 deletions(-) diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index f2c600d459..30cdb0f3ea 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -17,12 +17,8 @@ metrics can be filtered for finer grain analysis. - [Metric instruments](#metric-instruments) - [RPC server](#rpc-server) - [Metric: `rpc.server.call.duration`](#metric-rpcservercallduration) - - [Metric: `rpc.server.request.size`](#metric-rpcserverrequestsize) - - [Metric: `rpc.server.response.size`](#metric-rpcserverresponsesize) - [RPC client](#rpc-client) - [Metric: `rpc.client.call.duration`](#metric-rpcclientcallduration) - - [Metric: `rpc.client.request.size`](#metric-rpcclientrequestsize) - - [Metric: `rpc.client.response.size`](#metric-rpcclientresponsesize) - [Semantic Conventions for specific RPC technologies](#semantic-conventions-for-specific-rpc-technologies) @@ -185,240 +181,6 @@ different processes could be listening on TCP port 12345 and UDP port 12345. -#### Metric: `rpc.server.request.size` - -This metric is [recommended][MetricRecommended]. - - - - - - -| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | -| -------- | --------------- | ----------- | -------------- | --------- | ------ | -| `rpc.server.request.size` | Histogram | `By` | Measures the size of RPC request messages (uncompressed). [1] | ![Development](https://img.shields.io/badge/-development-blue) | | - -**[1]:** **Streaming**: Recorded per message in a streaming batch - -**Attributes:** - -| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | -| --- | --- | --- | --- | --- | --- | -| [`rpc.system.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The Remote Procedure Call (RPC) system. [1] | `grpc`; `dubbo`; `connectrpc` | -| [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [5] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [6] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [7] | `tcp`; `udp` | -| [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). | `example.com`; `10.1.2.80`; `/tmp/my.sock` | -| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | int | Server port number. | `80`; `8080`; `443` | - -**[1] `rpc.system.name`:** The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - -**[2] `error.type`:** If the RPC fails with an error before status code is returned, -`error.type` SHOULD be set to the exception type (its fully-qualified class name, if applicable) -or a component-specific, low cardinality error identifier. - -If a response status code is returned and status indicates an error, -`error.type` SHOULD be set to that status code. Check system-specific conventions -for the details on which values of `rpc.response.status_code` are considered errors. - -The `error.type` value SHOULD be predictable and SHOULD have low cardinality. -Instrumentations SHOULD document the list of errors they report. - -If the request has completed successfully, instrumentations SHOULD NOT set -`error.type`. - -**[3] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. - -Some RPC frameworks or libraries provide a fixed set of recognized methods -for client stubs and server implementations. Instrumentations for such -frameworks MUST set this attribute to the original method name only -when the method is recognized by the framework or library. - -When the method is not recognized, for example, when the server receives -a request for a method that is not predefined on the server, or when -instrumentation is not able to reliably detect if the method is predefined, -the attribute MUST be set to `_OTHER`. In such cases, tracing -instrumentations MUST also set `rpc.method_original` attribute to -the original method value. - -If the RPC instrumentation could end up converting valid RPC methods to -`_OTHER`, then it SHOULD provide a way to configure the list of recognized -RPC methods. - -The `rpc.method` can be different from the name of any implementing -method/function. -The `code.function.name` attribute may be used to record the fully-qualified -method actually executing the call on the server side, or the -RPC client stub method on the client side. - -**[4] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. -Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - -**[5] `network.protocol.name`:** The value SHOULD be normalized to lowercase. - -**[6] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. - -**[7] `network.transport`:** The value SHOULD be normalized to lowercase. - -Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport. For example -different processes could be listening on TCP port 12345 and UDP port 12345. - ---- - -`error.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 | Stability | -| --- | --- | --- | -| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - ---- - -`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 | Stability | -| --- | --- | --- | -| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `quic` | QUIC | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - ---- - -`rpc.system.name` 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 | Stability | -| --- | --- | --- | -| `connectrpc` | [Connect RPC](https://connectrpc.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `dubbo` | [Apache Dubbo](https://dubbo.apache.org/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `grpc` | [gRPC](https://grpc.io/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `jsonrpc` | [JSON-RPC](https://www.jsonrpc.org/) | ![Development](https://img.shields.io/badge/-development-blue) | - - - - - -#### Metric: `rpc.server.response.size` - -This metric is [recommended][MetricRecommended]. - - - - - - -| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | -| -------- | --------------- | ----------- | -------------- | --------- | ------ | -| `rpc.server.response.size` | Histogram | `By` | Measures the size of RPC response messages (uncompressed). [1] | ![Development](https://img.shields.io/badge/-development-blue) | | - -**[1]:** **Streaming**: Recorded per response in a streaming batch - -**Attributes:** - -| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | -| --- | --- | --- | --- | --- | --- | -| [`rpc.system.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The Remote Procedure Call (RPC) system. [1] | `grpc`; `dubbo`; `connectrpc` | -| [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [5] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [6] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [7] | `tcp`; `udp` | -| [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). | `example.com`; `10.1.2.80`; `/tmp/my.sock` | -| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Opt-In` | int | Server port number. | `80`; `8080`; `443` | - -**[1] `rpc.system.name`:** The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - -**[2] `error.type`:** If the RPC fails with an error before status code is returned, -`error.type` SHOULD be set to the exception type (its fully-qualified class name, if applicable) -or a component-specific, low cardinality error identifier. - -If a response status code is returned and status indicates an error, -`error.type` SHOULD be set to that status code. Check system-specific conventions -for the details on which values of `rpc.response.status_code` are considered errors. - -The `error.type` value SHOULD be predictable and SHOULD have low cardinality. -Instrumentations SHOULD document the list of errors they report. - -If the request has completed successfully, instrumentations SHOULD NOT set -`error.type`. - -**[3] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. - -Some RPC frameworks or libraries provide a fixed set of recognized methods -for client stubs and server implementations. Instrumentations for such -frameworks MUST set this attribute to the original method name only -when the method is recognized by the framework or library. - -When the method is not recognized, for example, when the server receives -a request for a method that is not predefined on the server, or when -instrumentation is not able to reliably detect if the method is predefined, -the attribute MUST be set to `_OTHER`. In such cases, tracing -instrumentations MUST also set `rpc.method_original` attribute to -the original method value. - -If the RPC instrumentation could end up converting valid RPC methods to -`_OTHER`, then it SHOULD provide a way to configure the list of recognized -RPC methods. - -The `rpc.method` can be different from the name of any implementing -method/function. -The `code.function.name` attribute may be used to record the fully-qualified -method actually executing the call on the server side, or the -RPC client stub method on the client side. - -**[4] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. -Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - -**[5] `network.protocol.name`:** The value SHOULD be normalized to lowercase. - -**[6] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. - -**[7] `network.transport`:** The value SHOULD be normalized to lowercase. - -Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport. For example -different processes could be listening on TCP port 12345 and UDP port 12345. - ---- - -`error.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 | Stability | -| --- | --- | --- | -| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - ---- - -`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 | Stability | -| --- | --- | --- | -| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `quic` | QUIC | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - ---- - -`rpc.system.name` 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 | Stability | -| --- | --- | --- | -| `connectrpc` | [Connect RPC](https://connectrpc.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `dubbo` | [Apache Dubbo](https://dubbo.apache.org/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `grpc` | [gRPC](https://grpc.io/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `jsonrpc` | [JSON-RPC](https://www.jsonrpc.org/) | ![Development](https://img.shields.io/badge/-development-blue) | - - - - - ### RPC client Below is a list of RPC client metric instruments. @@ -551,252 +313,6 @@ different processes could be listening on TCP port 12345 and UDP port 12345. -#### Metric: `rpc.client.request.size` - -This metric is [recommended][MetricRecommended]. - - - - - - -| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | -| -------- | --------------- | ----------- | -------------- | --------- | ------ | -| `rpc.client.request.size` | Histogram | `By` | Measures the size of RPC request messages (uncompressed). [1] | ![Development](https://img.shields.io/badge/-development-blue) | | - -**[1]:** **Streaming**: Recorded per message in a streaming batch - -**Attributes:** - -| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | -| --- | --- | --- | --- | --- | --- | -| [`rpc.system.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The Remote Procedure Call (RPC) system. [1] | `grpc`; `dubbo`; `connectrpc` | -| [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If available. | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | -| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [6] | int | Server port number. [7] | `80`; `8080`; `443` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [8] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [9] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [10] | `tcp`; `udp` | - -**[1] `rpc.system.name`:** The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - -**[2] `error.type`:** If the RPC fails with an error before status code is returned, -`error.type` SHOULD be set to the exception type (its fully-qualified class name, if applicable) -or a component-specific, low cardinality error identifier. - -If a response status code is returned and status indicates an error, -`error.type` SHOULD be set to that status code. Check system-specific conventions -for the details on which values of `rpc.response.status_code` are considered errors. - -The `error.type` value SHOULD be predictable and SHOULD have low cardinality. -Instrumentations SHOULD document the list of errors they report. - -If the request has completed successfully, instrumentations SHOULD NOT set -`error.type`. - -**[3] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. - -Some RPC frameworks or libraries provide a fixed set of recognized methods -for client stubs and server implementations. Instrumentations for such -frameworks MUST set this attribute to the original method name only -when the method is recognized by the framework or library. - -When the method is not recognized, for example, when the server receives -a request for a method that is not predefined on the server, or when -instrumentation is not able to reliably detect if the method is predefined, -the attribute MUST be set to `_OTHER`. In such cases, tracing -instrumentations MUST also set `rpc.method_original` attribute to -the original method value. - -If the RPC instrumentation could end up converting valid RPC methods to -`_OTHER`, then it SHOULD provide a way to configure the list of recognized -RPC methods. - -The `rpc.method` can be different from the name of any implementing -method/function. -The `code.function.name` attribute may be used to record the fully-qualified -method actually executing the call on the server side, or the -RPC client stub method on the client side. - -**[4] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. -Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - -**[5] `server.address`:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. - -**[6] `server.port`:** if `server.address` is set and if the port is supported by the network transport used for communication. - -**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. - -**[8] `network.protocol.name`:** The value SHOULD be normalized to lowercase. - -**[9] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. - -**[10] `network.transport`:** The value SHOULD be normalized to lowercase. - -Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport. For example -different processes could be listening on TCP port 12345 and UDP port 12345. - ---- - -`error.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 | Stability | -| --- | --- | --- | -| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - ---- - -`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 | Stability | -| --- | --- | --- | -| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `quic` | QUIC | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - ---- - -`rpc.system.name` 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 | Stability | -| --- | --- | --- | -| `connectrpc` | [Connect RPC](https://connectrpc.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `dubbo` | [Apache Dubbo](https://dubbo.apache.org/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `grpc` | [gRPC](https://grpc.io/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `jsonrpc` | [JSON-RPC](https://www.jsonrpc.org/) | ![Development](https://img.shields.io/badge/-development-blue) | - - - - - -#### Metric: `rpc.client.response.size` - -This metric is [recommended][MetricRecommended]. - - - - - - -| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | -| -------- | --------------- | ----------- | -------------- | --------- | ------ | -| `rpc.client.response.size` | Histogram | `By` | Measures the size of RPC response messages (uncompressed). [1] | ![Development](https://img.shields.io/badge/-development-blue) | | - -**[1]:** **Streaming**: Recorded per response in a streaming batch - -**Attributes:** - -| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | -| --- | --- | --- | --- | --- | --- | -| [`rpc.system.name`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The Remote Procedure Call (RPC) system. [1] | `grpc`; `dubbo`; `connectrpc` | -| [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | -| [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | The fully-qualified logical name of the method from the RPC interface perspective. [3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | -| [`rpc.response.status_code`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if available. | string | Status code of the RPC returned by the RPC server or generated by the client [4] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | -| [`server.address`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If available. | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | -| [`server.port`](/docs/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [6] | int | Server port number. [7] | `80`; `8080`; `443` | -| [`network.protocol.name`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [8] | `http` | -| [`network.protocol.version`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | The actual version of the protocol used for network communication. [9] | `1.1`; `2` | -| [`network.transport`](/docs/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [10] | `tcp`; `udp` | - -**[1] `rpc.system.name`:** The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC. - -**[2] `error.type`:** If the RPC fails with an error before status code is returned, -`error.type` SHOULD be set to the exception type (its fully-qualified class name, if applicable) -or a component-specific, low cardinality error identifier. - -If a response status code is returned and status indicates an error, -`error.type` SHOULD be set to that status code. Check system-specific conventions -for the details on which values of `rpc.response.status_code` are considered errors. - -The `error.type` value SHOULD be predictable and SHOULD have low cardinality. -Instrumentations SHOULD document the list of errors they report. - -If the request has completed successfully, instrumentations SHOULD NOT set -`error.type`. - -**[3] `rpc.method`:** The method name MAY have unbounded cardinality in edge or error cases. - -Some RPC frameworks or libraries provide a fixed set of recognized methods -for client stubs and server implementations. Instrumentations for such -frameworks MUST set this attribute to the original method name only -when the method is recognized by the framework or library. - -When the method is not recognized, for example, when the server receives -a request for a method that is not predefined on the server, or when -instrumentation is not able to reliably detect if the method is predefined, -the attribute MUST be set to `_OTHER`. In such cases, tracing -instrumentations MUST also set `rpc.method_original` attribute to -the original method value. - -If the RPC instrumentation could end up converting valid RPC methods to -`_OTHER`, then it SHOULD provide a way to configure the list of recognized -RPC methods. - -The `rpc.method` can be different from the name of any implementing -method/function. -The `code.function.name` attribute may be used to record the fully-qualified -method actually executing the call on the server side, or the -RPC client stub method on the client side. - -**[4] `rpc.response.status_code`:** Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. -Semantic conventions for individual RPC frameworks SHOULD document what `rpc.response.status_code` means in the context of that system and which values are considered to represent errors. - -**[5] `server.address`:** May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `server.address` to the IP address provided in the host component. - -**[6] `server.port`:** if `server.address` is set and if the port is supported by the network transport used for communication. - -**[7] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. - -**[8] `network.protocol.name`:** The value SHOULD be normalized to lowercase. - -**[9] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. - -**[10] `network.transport`:** The value SHOULD be normalized to lowercase. - -Consider always setting the transport when setting a port number, since -a port number is ambiguous without knowing the transport. For example -different processes could be listening on TCP port 12345 and UDP port 12345. - ---- - -`error.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 | Stability | -| --- | --- | --- | -| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - ---- - -`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 | Stability | -| --- | --- | --- | -| `pipe` | Named or anonymous pipe. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `quic` | QUIC | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `tcp` | TCP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - ---- - -`rpc.system.name` 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 | Stability | -| --- | --- | --- | -| `connectrpc` | [Connect RPC](https://connectrpc.com/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `dubbo` | [Apache Dubbo](https://dubbo.apache.org/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `grpc` | [gRPC](https://grpc.io/) | ![Development](https://img.shields.io/badge/-development-blue) | -| `jsonrpc` | [JSON-RPC](https://www.jsonrpc.org/) | ![Development](https://img.shields.io/badge/-development-blue) | - - - - - ## Semantic Conventions for specific RPC technologies More specific Semantic Conventions are defined for the following RPC technologies: diff --git a/model/rpc/deprecated/metrics-deprecated.yaml b/model/rpc/deprecated/metrics-deprecated.yaml index 062aad5a6f..14874e5137 100644 --- a/model/rpc/deprecated/metrics-deprecated.yaml +++ b/model/rpc/deprecated/metrics-deprecated.yaml @@ -114,3 +114,72 @@ groups: reason: uncategorized note: Replaced by `rpc.client.call.duration` with unit `s`. brief: "Deprecated, use `rpc.client.call.duration` instead. Note: the unit also changed from `ms` to `s`." + + + - id: metric.rpc.server.request.size + type: metric + metric_name: rpc.server.request.size + annotations: + code_generation: + metric_value_type: int + stability: development + brief: Measures the size of RPC request messages (uncompressed). + instrument: histogram + unit: "By" + note: | + **Streaming**: Recorded per message in a streaming batch + extends: attributes.metrics.rpc.server + deprecated: + reason: obsoleted + note: Removed, no replacement at this time. + + - id: metric.rpc.server.response.size + type: metric + metric_name: rpc.server.response.size + annotations: + code_generation: + metric_value_type: int + stability: development + brief: Measures the size of RPC response messages (uncompressed). + instrument: histogram + unit: "By" + note: | + **Streaming**: Recorded per response in a streaming batch + extends: attributes.metrics.rpc.server + deprecated: + reason: obsoleted + note: Removed, no replacement at this time. + + - id: metric.rpc.client.request.size + type: metric + metric_name: rpc.client.request.size + annotations: + code_generation: + metric_value_type: int + stability: development + brief: Measures the size of RPC request messages (uncompressed). + instrument: histogram + unit: "By" + note: | + **Streaming**: Recorded per message in a streaming batch + extends: attributes.metrics.rpc.client + deprecated: + reason: obsoleted + note: Removed, no replacement at this time. + + - id: metric.rpc.client.response.size + type: metric + metric_name: rpc.client.response.size + annotations: + code_generation: + metric_value_type: int + stability: development + brief: Measures the size of RPC response messages (uncompressed). + instrument: histogram + unit: "By" + note: | + **Streaming**: Recorded per response in a streaming batch + extends: attributes.metrics.rpc.client + deprecated: + reason: obsoleted + note: Removed, no replacement at this time. diff --git a/model/rpc/metrics.yaml b/model/rpc/metrics.yaml index d710715659..96f31aca06 100644 --- a/model/rpc/metrics.yaml +++ b/model/rpc/metrics.yaml @@ -46,34 +46,6 @@ groups: extends: attributes.metrics.rpc.server - - id: metric.rpc.server.request.size - type: metric - metric_name: rpc.server.request.size - annotations: - code_generation: - metric_value_type: int - stability: development - brief: Measures the size of RPC request messages (uncompressed). - instrument: histogram - unit: "By" - note: | - **Streaming**: Recorded per message in a streaming batch - extends: attributes.metrics.rpc.server - - - id: metric.rpc.server.response.size - type: metric - metric_name: rpc.server.response.size - annotations: - code_generation: - metric_value_type: int - stability: development - brief: Measures the size of RPC response messages (uncompressed). - instrument: histogram - unit: "By" - note: | - **Streaming**: Recorded per response in a streaming batch - extends: attributes.metrics.rpc.server - # RPC Client metrics - id: metric.rpc.client.call.duration type: metric @@ -89,31 +61,3 @@ groups: 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 - type: metric - metric_name: rpc.client.request.size - annotations: - code_generation: - metric_value_type: int - stability: development - brief: Measures the size of RPC request messages (uncompressed). - instrument: histogram - unit: "By" - note: | - **Streaming**: Recorded per message in a streaming batch - extends: attributes.metrics.rpc.client - - - id: metric.rpc.client.response.size - type: metric - metric_name: rpc.client.response.size - annotations: - code_generation: - metric_value_type: int - stability: development - brief: Measures the size of RPC response messages (uncompressed). - instrument: histogram - unit: "By" - note: | - **Streaming**: Recorded per response in a streaming batch - extends: attributes.metrics.rpc.client From 3078aa0eb3a2523f89b96ca7fd2bc65da3c39848 Mon Sep 17 00:00:00 2001 From: liudmila molkova Date: Sat, 10 Jan 2026 12:17:51 -0800 Subject: [PATCH 2/4] changelog --- .chloggen/rpc-deprecate-size-metrics.yaml | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .chloggen/rpc-deprecate-size-metrics.yaml diff --git a/.chloggen/rpc-deprecate-size-metrics.yaml b/.chloggen/rpc-deprecate-size-metrics.yaml new file mode 100644 index 0000000000..af6c924abb --- /dev/null +++ b/.chloggen/rpc-deprecate-size-metrics.yaml @@ -0,0 +1,6 @@ +change_type: deprecation +component: rpc +note: > + Deprecate `rpc.server.request.size`, `rpc.server.response.size`, `rpc.client.request.size`, + and `rpc.client.response.size` metrics due to confusing definition and low adoption. +issues: [TODO] From 5f467c9e121f70a00b9dc5b19beda3ac27ccf9de Mon Sep 17 00:00:00 2001 From: liudmila molkova Date: Sat, 10 Jan 2026 12:35:00 -0800 Subject: [PATCH 3/4] changelog --- .chloggen/rpc-deprecate-size-metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.chloggen/rpc-deprecate-size-metrics.yaml b/.chloggen/rpc-deprecate-size-metrics.yaml index af6c924abb..40ae51dc1f 100644 --- a/.chloggen/rpc-deprecate-size-metrics.yaml +++ b/.chloggen/rpc-deprecate-size-metrics.yaml @@ -3,4 +3,4 @@ component: rpc note: > Deprecate `rpc.server.request.size`, `rpc.server.response.size`, `rpc.client.request.size`, and `rpc.client.response.size` metrics due to confusing definition and low adoption. -issues: [TODO] +issues: [3267] From 590d0bcaad80ecb0519f020c7c45e48bfb2efb57 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 14 Jan 2026 13:15:13 -0800 Subject: [PATCH 4/4] Update .chloggen/rpc-deprecate-size-metrics.yaml Co-authored-by: Matthew Hensley <130569+matt-hensley@users.noreply.github.com> --- .chloggen/rpc-deprecate-size-metrics.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.chloggen/rpc-deprecate-size-metrics.yaml b/.chloggen/rpc-deprecate-size-metrics.yaml index 40ae51dc1f..eaddd28b7f 100644 --- a/.chloggen/rpc-deprecate-size-metrics.yaml +++ b/.chloggen/rpc-deprecate-size-metrics.yaml @@ -1,6 +1,6 @@ change_type: deprecation component: rpc note: > - Deprecate `rpc.server.request.size`, `rpc.server.response.size`, `rpc.client.request.size`, - and `rpc.client.response.size` metrics due to confusing definition and low adoption. + Deprecate experimental `rpc.server.request.size`, `rpc.server.response.size`, `rpc.client.request.size`, + and `rpc.client.response.size` metrics due to ambiguous definitions and inconsistent implementation. issues: [3267]