From a5bc6b08766ff7f979ae4321d1db567a7708f45f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Wed, 9 Jun 2021 13:01:33 +0200 Subject: [PATCH 1/4] Remove rpc.jsonrpc.method, clarify rpc.method instead. --- CHANGELOG.md | 2 ++ semantic_conventions/trace/rpc.yaml | 20 ++++++++++++------- .../metrics/semantic_conventions/rpc.md | 8 ++++++-- .../instrumentation/aws-sdk.md | 8 ++++++-- .../trace/semantic_conventions/rpc.md | 13 +++++++++--- 5 files changed, 37 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 92d132d922f..bd2e529c67d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,8 @@ release. ### Semantic Conventions +- Remove `rpc.jsonrpc.method`, clarify that `rpc.method` should be used instead. + ### Compatibility ### OpenTelemetry Protocol diff --git a/semantic_conventions/trace/rpc.yaml b/semantic_conventions/trace/rpc.yaml index b34d774e4d7..2f8c09cb95b 100644 --- a/semantic_conventions/trace/rpc.yaml +++ b/semantic_conventions/trace/rpc.yaml @@ -12,13 +12,22 @@ 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). 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. examples: "exampleMethod" - ref: net.peer.ip - ref: net.peer.name @@ -89,11 +98,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 +112,5 @@ groups: type: string brief: "`error.message` property of response if it is an error response." examples: ['Parse error', 'User already exists'] + constraints: + - any_of: ['rpc.method'] diff --git a/specification/metrics/semantic_conventions/rpc.md b/specification/metrics/semantic_conventions/rpc.md index a050f6b5ca5..191d45582b8 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). + +**[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. + **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 01b8dd580b3..d896df83f52 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. + +**[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). ## DynamoDB diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index 4212c7909bb..eedd838195d 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). + +**[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. + **Additional attribute requirements:** At least one of the following sets of attributes is required: * [`net.peer.ip`](span-general.md) @@ -180,8 +184,11 @@ 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 | + +**Additional attribute requirements:** At least one of the following sets of attributes is required: + +* `rpc.method` From 1d75044e38b9fbd5c4cc111c35dbc06282545651 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Wed, 9 Jun 2021 13:07:24 +0200 Subject: [PATCH 2/4] Add PR#. --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index bd2e529c67d..0a25e167053 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,7 @@ 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 From ce3512baf6d081e04ef43593c7f335fce1927e18 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Thu, 10 Jun 2021 10:05:56 +0200 Subject: [PATCH 3/4] Clarify client side code.namespace/function. --- semantic_conventions/trace/rpc.yaml | 8 ++++++-- specification/metrics/semantic_conventions/rpc.md | 4 ++-- .../trace/semantic_conventions/instrumentation/aws-sdk.md | 4 ++-- specification/trace/semantic_conventions/rpc.md | 4 ++-- 4 files changed, 12 insertions(+), 8 deletions(-) diff --git a/semantic_conventions/trace/rpc.yaml b/semantic_conventions/trace/rpc.yaml index 2f8c09cb95b..360cfbb3d40 100644 --- a/semantic_conventions/trace/rpc.yaml +++ b/semantic_conventions/trace/rpc.yaml @@ -17,7 +17,9 @@ groups: 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). + (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 @@ -27,7 +29,9 @@ groups: 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. + 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 diff --git a/specification/metrics/semantic_conventions/rpc.md b/specification/metrics/semantic_conventions/rpc.md index 191d45582b8..fa3d5159749 100644 --- a/specification/metrics/semantic_conventions/rpc.md +++ b/specification/metrics/semantic_conventions/rpc.md @@ -68,9 +68,9 @@ or not they should be on the server, client or both. | [`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). +**[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. +**[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: diff --git a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md index d896df83f52..a08359e6d02 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-sdk.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-sdk.md @@ -22,9 +22,9 @@ with the naming guidelines for RPC client spans. | [`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. +**[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). +**[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 eedd838195d..3986e2ec6fc 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -65,9 +65,9 @@ Examples of span names: | [`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). +**[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. +**[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: From b6fd5cede0f588a0a4dd6e4dd1736045d9fac1b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Thu, 10 Jun 2021 10:07:15 +0200 Subject: [PATCH 4/4] 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. --- semantic_conventions/trace/rpc.yaml | 7 +++++-- specification/trace/semantic_conventions/rpc.md | 5 ++--- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/semantic_conventions/trace/rpc.yaml b/semantic_conventions/trace/rpc.yaml index 360cfbb3d40..60fe04f03ad 100644 --- a/semantic_conventions/trace/rpc.yaml +++ b/semantic_conventions/trace/rpc.yaml @@ -116,5 +116,8 @@ groups: type: string brief: "`error.message` property of response if it is an error response." examples: ['Parse error', 'User already exists'] - constraints: - - any_of: ['rpc.method'] + - 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/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index 3986e2ec6fc..214ae629764 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -187,8 +187,7 @@ Conventions specific to [JSON RPC](https://www.jsonrpc.org/). | `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 | -**Additional attribute requirements:** At least one of the following sets of attributes is required: - -* `rpc.method` +**[1]:** This is always required for jsonrpc. See the note in the general RPC conventions for more information.