From 795e4ec00fb296f4143d526266e3c7eccd0df258 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 15 Jun 2021 01:59:09 +0200 Subject: [PATCH] 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 https://github.com/open-telemetry/build-tools/issues/33 is resolved & the updated build tools available. Co-authored-by: Armin Ruech --- semantic_conventions/trace/rpc.yaml | 27 ++++++++++++++----- .../metrics/semantic_conventions/rpc.md | 8 ++++-- .../instrumentation/aws-sdk.md | 8 ++++-- .../trace/semantic_conventions/rpc.md | 12 ++++++--- 4 files changed, 41 insertions(+), 14 deletions(-) diff --git a/semantic_conventions/trace/rpc.yaml b/semantic_conventions/trace/rpc.yaml index b34d774e4d..60fe04f03a 100644 --- 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 index a050f6b5ca..fa3d515974 100644 --- 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 index 01b8dd580b..a08359e6d0 100644 --- 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. | 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). ## DynamoDB diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index 4212c7909b..214ae62976 100644 --- 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.