Remove rpc.jsonrpc.method, clarify rpc.method instead. (#1748)

* Remove rpc.jsonrpc.method, clarify rpc.method instead. * Add PR#. * Clarify client side code.namespace/function. * Use "ref" instead of "constraint: any_of". This should be changed back once open-telemetry/build-tools#33 is resolved & the updated build tools available. Co-authored-by: Armin Ruech <[email protected]>
open-telemetry · Jun 14, 2021 · d271b73 · d271b73
1 parent cfd77a8
commit d271b73
Show file tree

Hide file tree

Showing 5 changed files with 44 additions and 14 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -19,6 +19,9 @@ release.
 
 ### Semantic Conventions
 
+- Remove `rpc.jsonrpc.method`, clarify that `rpc.method` should be used instead.
+  ([#1748](https://github.com/open-telemetry/opentelemetry-specification/pull/1748))
+
 ### Compatibility
 
 ### OpenTelemetry Protocol

diff --git a/semantic_conventions/trace/rpc.yaml b/semantic_conventions/trace/rpc.yaml
@@ -12,13 +12,26 @@ groups:
           type: string
           required:
             conditional: "No, but recommended"
-          brief: 'The full name of the service being called, including its package name, if applicable.'
+          brief: 'The full (logical) name of the service being called, including its package name, if applicable.'
+          note: >
+            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.namespace` attribute may be used to store the latter
+            (despite the attribute name, it may include a class name;
+            e.g., class with method actually executing the call on the server side,
+            RPC client stub class on the client side).
           examples: "myservice.EchoService"
         - id: method
           type: string
           required:
             conditional: "No, but recommended"
-          brief: 'The name of the method being called, must be equal to the $method part in the span name.'
+          brief: 'The name of the (logical) method being called, must be equal to the $method part in the span name.'
+          note: >
+            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` attribute may be used to store the latter
+            (e.g., method actually executing the call on the server side,
+            RPC client stub method on the client side).
           examples: "exampleMethod"
         - ref: net.peer.ip
         - ref: net.peer.name
@@ -89,11 +102,6 @@ groups:
             conditional: 'If missing, it is assumed to be "1.0".'
           brief: "Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 does not specify this, the value can be omitted."
           examples: ['2.0', '1.0']
-        - id: method
-          type: string
-          required: always
-          brief: "`method` property from request. Unlike `rpc.method`, this may not relate to the actual method being called. Useful for client-side traces since client does not know what will be called on the server."
-          examples: ['users.create', 'get_users']
         - id: request_id
           type: string
           brief: "`id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification."
@@ -108,3 +116,8 @@ groups:
           type: string
           brief: "`error.message` property of response if it is an error response."
           examples: ['Parse error', 'User already exists']
+        - ref: rpc.method
+          required: always
+          note: >
+           This is always required for jsonrpc. See the note in the general
+           RPC conventions for more information.
diff --git a/specification/metrics/semantic_conventions/rpc.md b/specification/metrics/semantic_conventions/rpc.md
@@ -61,13 +61,17 @@ or not they should be on the server, client or both.
 | Attribute  | Type | Description  | Examples  | Required |
 |---|---|---|---|---|
 | [`rpc.system`](../../trace/semantic_conventions/rpc.md) | string | A string identifying the remoting system. | `grpc`; `java_rmi`; `wcf` | Yes |
-| [`rpc.service`](../../trace/semantic_conventions/rpc.md) | string | The full name of the service being called, including its package name, if applicable. | `myservice.EchoService` | No, but recommended |
-| [`rpc.method`](../../trace/semantic_conventions/rpc.md) | string | The name of the method being called, must be equal to the $method part in the span name. | `exampleMethod` | No, but recommended |
+| [`rpc.service`](../../trace/semantic_conventions/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | No, but recommended |
+| [`rpc.method`](../../trace/semantic_conventions/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | No, but recommended |
 | [`net.peer.ip`](../../trace/semantic_conventions/span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | See below |
 | [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | Remote hostname or similar, see note below. | `example.com` | See below |
 | [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Remote port number. | `80`; `8080`; `443` | See below |
 | [`net.transport`](../../trace/semantic_conventions/span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | See below |
 
+**[1]:** 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.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+
+**[2]:** 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` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+
 **Additional attribute requirements:** At least one of the following sets of attributes is required:
 
 * [`net.peer.ip`](../../trace/semantic_conventions/span-general.md)

diff --git a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md
@@ -18,9 +18,13 @@ with the naming guidelines for RPC client spans.
 <!-- semconv aws -->
 | Attribute  | Type | Description  | Examples  | Required |
 |---|---|---|---|---|
-| [`rpc.method`](../rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK | `GetItem`; `PutItem` | No |
-| [`rpc.service`](../rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. | `DynamoDB`; `S3` | No |
+| [`rpc.method`](../rpc.md) | string | The name of the operation corresponding to the request, as returned by the AWS SDK [1] | `GetItem`; `PutItem` | No |
+| [`rpc.service`](../rpc.md) | string | The name of the service to which a request is made, as returned by the AWS SDK. [2] | `DynamoDB`; `S3` | No |
 | [`rpc.system`](../rpc.md) | string | The value `aws-api`. | `aws-api` | Yes |
+
+**[1]:** 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` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+
+**[2]:** 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.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
 <!-- endsemconv -->
 
 ## DynamoDB

diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md
@@ -58,13 +58,17 @@ Examples of span names:
 | Attribute  | Type | Description  | Examples  | Required |
 |---|---|---|---|---|
 | `rpc.system` | string | A string identifying the remoting system. | `grpc`; `java_rmi`; `wcf` | Yes |
-| `rpc.service` | string | The full name of the service being called, including its package name, if applicable. | `myservice.EchoService` | No, but recommended |
-| `rpc.method` | string | The name of the method being called, must be equal to the $method part in the span name. | `exampleMethod` | No, but recommended |
+| `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | No, but recommended |
+| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | No, but recommended |
 | [`net.peer.ip`](span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | See below |
 | [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. | `example.com` | See below |
 | [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | See below |
 | [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | See below |
 
+**[1]:** 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.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
+
+**[2]:** 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` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
+
 **Additional attribute requirements:** At least one of the following sets of attributes is required:
 
 * [`net.peer.ip`](span-general.md)
@@ -180,8 +184,10 @@ Conventions specific to [JSON RPC](https://www.jsonrpc.org/).
 | Attribute  | Type | Description  | Examples  | Required |
 |---|---|---|---|---|
 | `rpc.jsonrpc.version` | string | Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 does not specify this, the value can be omitted. | `2.0`; `1.0` | If missing, it is assumed to be "1.0". |
-| `rpc.jsonrpc.method` | string | `method` property from request. Unlike `rpc.method`, this may not relate to the actual method being called. Useful for client-side traces since client does not know what will be called on the server. | `users.create`; `get_users` | Yes |
 | `rpc.jsonrpc.request_id` | string | `id` property of request or response. Since protocol allows id to be int, string, `null` or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of `null` value. Omit entirely if this is a notification. | `10`; `request-7`; `` | No |
 | `rpc.jsonrpc.error_code` | int | `error.code` property of response if it is an error response. | `-32700`; `100` | If missing, response is assumed to be successful. |
 | `rpc.jsonrpc.error_message` | string | `error.message` property of response if it is an error response. | `Parse error`; `User already exists` | No |
+| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [1] | `exampleMethod` | Yes |
+
+**[1]:** This is always required for jsonrpc. See the note in the general RPC conventions for more information.
 <!-- endsemconv -->