Merge rpc.method and rpc.service into fully-qualified rpc.method, clarify span name and possible high cardinality (#3223)

Co-authored-by: Matthew Hensley <[email protected]>

Author: lmolkova

.chloggen/rpc-method-service.yaml

@@ -0,0 +1,6 @@
+change_type: breaking
+component: rpc
+note: Merge `rpc.method` and `rpc.service` into fully-qualified `rpc.method`
+  attribute. Clarify how to handle possible high cardinality of `rpc.method`
+  in edge cases. Clarify `rpc.method` usage in span names.
+issues: [2863, 3196, 3223]

docs/cloud-providers/aws-sdk.md

@@ -45,7 +45,7 @@ interesting conventions are found.
 | [`aws.request_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS request ID as returned in the response headers `x-amzn-requestid`, `x-amzn-request-id` or `x-amz-request-id`. | `79b9da39-b7ae-508a-a6bc-864b2829c622`; `C9ER4AJX75574TDJ` |
 | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [1] | `us-east-1`; `us-west-2` |
 | [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` |
-| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` |
+| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Value should be included in `rpc.method` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` |
 
 **[1] `cloud.region`:** Specifies the AWS Region that the SDK client targets for a given AWS service call. The attribute's value should adhere to the AWS Region codes outlined in the [AWS documentation](https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html#available-regions).
 

docs/db/dynamodb.md

@@ -34,7 +34,7 @@ Semantic Conventions for AWS S3 client spans extend the general [AWS SDK Semanti
 | [`aws.s3.upload_id`](/docs/registry/attributes/aws.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Upload ID that identifies the multipart upload. [6] | `dfRtDYWFbkRONycy.Yxwh66Yjlx.cph0gtNBtJ` |
 | [`cloud.region`](/docs/registry/attributes/cloud.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The AWS Region where the requested service is being accessed. [7] | `us-east-1`; `us-west-2` |
 | [`rpc.method`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` |
-| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` |
+| [`rpc.service`](/docs/registry/attributes/rpc.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Value should be included in `rpc.method` which is expected to be a fully-qualified name. | `Recommended` | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` |
 
 **[1] `aws.s3.bucket`:** The `bucket` attribute is applicable to all S3 operations that reference a bucket, i.e. that require the bucket name as a mandatory parameter.
 This applies to almost all S3 operations except `list-buckets`.

docs/object-stores/s3.md

@@ -18,16 +18,38 @@ This document defines attributes for remote procedure calls.
 | <a id="rpc-message-id" href="#rpc-message-id">`rpc.message.id`</a> | ![Development](https://img.shields.io/badge/-development-blue) | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [1] | |
 | <a id="rpc-message-type" href="#rpc-message-type">`rpc.message.type`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | Whether this is a received or sent message. | `SENT`; `RECEIVED` |
 | <a id="rpc-message-uncompressed-size" href="#rpc-message-uncompressed-size">`rpc.message.uncompressed_size`</a> | ![Development](https://img.shields.io/badge/-development-blue) | int | Uncompressed size of the message in bytes. | |
-| <a id="rpc-method" href="#rpc-method">`rpc.method`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | This is the logical name of the method from the RPC interface perspective. [2] | `exampleMethod` |
+| <a id="rpc-method" href="#rpc-method">`rpc.method`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | The fully-qualified logical name of the method from the RPC interface perspective. [2] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` |
+| <a id="rpc-method-original" href="#rpc-method-original">`rpc.method_original`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | The original name of the method used by the client. | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` |
 | <a id="rpc-request-metadata" href="#rpc-request-metadata">`rpc.request.metadata.<key>`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string[] | RPC request metadata, `<key>` being the normalized RPC metadata key (lowercase), the value being the metadata values. [3] | `["1.2.3.4", "1.2.3.5"]` |
 | <a id="rpc-response-metadata" href="#rpc-response-metadata">`rpc.response.metadata.<key>`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string[] | RPC response metadata, `<key>` being the normalized RPC metadata key (lowercase), the value being the metadata values. [4] | `["attribute_value"]` |
 | <a id="rpc-response-status-code" href="#rpc-response-status-code">`rpc.response.status_code`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | Status code of the RPC returned by the RPC server or generated by the client [5] | `OK`; `DEADLINE_EXCEEDED`; `-32602` |
-| <a id="rpc-service" href="#rpc-service">`rpc.service`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | The full (logical) name of the service being called, including its package name, if applicable. [6] | `myservice.EchoService` |
-| <a id="rpc-system-name" href="#rpc-system-name">`rpc.system.name`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | The Remote Procedure Call (RPC) system. [7] | `grpc`; `dubbo`; `connectrpc` |
+| <a id="rpc-system-name" href="#rpc-system-name">`rpc.system.name`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | The Remote Procedure Call (RPC) system. [6] | `grpc`; `dubbo`; `connectrpc` |
 
 **[1] `rpc.message.id`:** This way we guarantee that the values will be consistent between different implementations.
 
-**[2] `rpc.method`:** This is the logical name of the method from the RPC interface perspective, which 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.
+**[2] `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.
 
 **[3] `rpc.request.metadata.<key>`:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured.
 Including all request metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
@@ -44,9 +66,7 @@ the `rpc.response.metadata.my-custom-key` attribute with value `["attribute_valu
 **[5] `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.
 
-**[6] `rpc.service`:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. 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 class on the client side.
-
-**[7] `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.
+**[6] `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.
 
 ---
 
@@ -90,6 +110,7 @@ Deprecated rpc message attributes.
 | <a id="rpc-jsonrpc-error-message" href="#rpc-jsonrpc-error-message">`rpc.jsonrpc.error_message`</a> | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Use the span status description or `error.message` attribute on other signals. | string | Deprecated, use span status description or `error.message` attribute on other signals. | `Parse error`; `User already exists` |
 | <a id="rpc-jsonrpc-request-id" href="#rpc-jsonrpc-request-id">`rpc.jsonrpc.request_id`</a> | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `jsonrpc.request.id`. | string | Deprecated, use `jsonrpc.request.id` instead. | `10`; `request-7`; `` |
 | <a id="rpc-jsonrpc-version" href="#rpc-jsonrpc-version">`rpc.jsonrpc.version`</a> | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `jsonrpc.protocol.version`. | string | Deprecated, use `jsonrpc.protocol.version` instead. | `2.0`; `1.0` |
+| <a id="rpc-service" href="#rpc-service">`rpc.service`</a> | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Value should be included in `rpc.method` which is expected to be a fully-qualified name. | string | Deprecated, use fully-qualified `rpc.method` instead. | `myservice.EchoService` |
 | <a id="rpc-system" href="#rpc-system">`rpc.system`</a> | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `rpc.system.name`. | string | Deprecated, use `rpc.system.name` attribute instead. | `grpc`; `java_rmi`; `dotnet_wcf` |
 
 ---