diff --git a/.chloggen/rpc_registry.yaml b/.chloggen/rpc_registry.yaml new file mode 100755 index 0000000000..1401a385e6 --- /dev/null +++ b/.chloggen/rpc_registry.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: breaking + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: rpc + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Rename`message.*` attributes under `rpc` to `rpc.message.*`. Deprecate old `message.*` attributes. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [854] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/attributes-registry/rpc.md b/docs/attributes-registry/rpc.md index 0c904e3f48..25f7a29087 100644 --- a/docs/attributes-registry/rpc.md +++ b/docs/attributes-registry/rpc.md @@ -20,8 +20,12 @@ RPC attributes are intended to be used in the context of events related to remot | `rpc.jsonrpc.error_message` | string | `error.message` property of response if it is an error response. | `Parse error`; `User already exists` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `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`; `` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `rpc.jsonrpc.version` | string | Protocol version as in `jsonrpc` property of request/response. Since JSON-RPC 1.0 doesn't specify this, the value can be omitted. | `2.0`; `1.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [5] | `exampleMethod` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [6] | `myservice.EchoService` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.message.compressed_size` | int | Compressed size of the message in bytes. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.message.id` | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [5] | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.message.type` | string | Whether this is a received or sent message. | `SENT` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.message.uncompressed_size` | int | Uncompressed size of the message in bytes. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [6] | `exampleMethod` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [7] | `myservice.EchoService` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** 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. @@ -32,9 +36,11 @@ RPC attributes are intended to be used in the context of events related to remot **[4]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information. -**[5]:** 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). +**[5]:** This way we guarantee that the values will be consistent between different implementations. -**[6]:** 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). +**[6]:** 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). + +**[7]:** 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). `rpc.connect_rpc.error_code` MUST be one of the following: @@ -79,6 +85,13 @@ RPC attributes are intended to be used in the context of events related to remot | `15` | DATA_LOSS | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `16` | UNAUTHENTICATED | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +`rpc.message.type` MUST be one of the following: + +| Value | Description | Stability | +|---|---|---| +| `SENT` | sent | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `RECEIVED` | received | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + `rpc.system` 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 | diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 20f1d09808..387f5b56b1 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -191,19 +191,19 @@ In the lifetime of an RPC stream, an event for each message sent/received on client and server spans SHOULD be created. In case of unary calls only one sent and one received message will be recorded for both client and server spans. - -The event name MUST be `message`. + +The event name MUST be `rpc.message`. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| `message.compressed_size` | int | Compressed size of the message in bytes. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `message.id` | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [1] | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `message.type` | string | Whether this is a received or sent message. | `SENT` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `message.uncompressed_size` | int | Uncompressed size of the message in bytes. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.message.compressed_size`](../attributes-registry/rpc.md) | int | Compressed size of the message in bytes. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.message.id`](../attributes-registry/rpc.md) | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [1] | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.message.type`](../attributes-registry/rpc.md) | string | Whether this is a received or sent message. | `SENT` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`rpc.message.uncompressed_size`](../attributes-registry/rpc.md) | int | Uncompressed size of the message in bytes. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** This way we guarantee that the values will be consistent between different implementations. -`message.type` MUST be one of the following: +`rpc.message.type` MUST be one of the following: | Value | Description | Stability | |---|---|---| diff --git a/model/registry/deprecated/rpc.yaml b/model/registry/deprecated/rpc.yaml new file mode 100644 index 0000000000..c6c36710fe --- /dev/null +++ b/model/registry/deprecated/rpc.yaml @@ -0,0 +1,32 @@ +groups: + - id: attributes.rpc.deprecated + type: attribute_group + brief: 'Deprecated rpc message attributes.' + attributes: + - id: message.type + type: + members: + - id: sent + value: "SENT" + stability: experimental + - id: received + value: "RECEIVED" + stability: experimental + stability: experimental + brief: "Deprecated, use `rpc.message.type` instead." + deprecated: "Replaced by `rpc.message.type`." + - id: message.id + type: int + stability: experimental + brief: "Deprecated, use `rpc.message.id` instead." + deprecated: "Replaced by `rpc.message.id`." + - id: message.compressed_size + type: int + stability: experimental + brief: "Deprecated, use `rpc.message.compressed_size` instead." + deprecated: "Replaced by `rpc.message.compressed_size`." + - id: message.uncompressed_size + type: int + stability: experimental + brief: "Deprecated, use `rpc.message.uncompressed_size` instead." + deprecated: "Replaced by `rpc.message.uncompressed_size`." diff --git a/model/registry/rpc.yaml b/model/registry/rpc.yaml index e7400d540e..d1e0aa05cf 100644 --- a/model/registry/rpc.yaml +++ b/model/registry/rpc.yaml @@ -239,3 +239,27 @@ groups: brief: 'Connect RPC' stability: experimental stability: experimental + - id: message.type + type: + members: + - id: sent + value: "SENT" + stability: experimental + - id: received + value: "RECEIVED" + stability: experimental + stability: experimental + brief: "Whether this is a received or sent message." + - id: message.id + type: int + stability: experimental + brief: "MUST be calculated as two different counters starting from `1` one for sent messages and one for received message." + note: "This way we guarantee that the values will be consistent between different implementations." + - id: message.compressed_size + type: int + stability: experimental + brief: "Compressed size of the message in bytes." + - id: message.uncompressed_size + type: int + stability: experimental + brief: "Uncompressed size of the message in bytes." diff --git a/model/trace/rpc.yaml b/model/trace/rpc.yaml index 7e259966f8..d578c6ba6a 100644 --- a/model/trace/rpc.yaml +++ b/model/trace/rpc.yaml @@ -8,9 +8,13 @@ groups: - ref: rpc.system requirement_level: required - ref: rpc.service + requirement_level: recommended - ref: rpc.method + requirement_level: recommended - ref: network.transport + requirement_level: recommended - ref: network.type + requirement_level: recommended - ref: server.address requirement_level: required brief: > @@ -29,6 +33,7 @@ groups: extends: rpc attributes: - ref: network.peer.address + requirement_level: recommended - ref: network.peer.port requirement_level: recommended: If `network.peer.address` is set. @@ -40,13 +45,18 @@ groups: brief: 'Semantic Convention for RPC server spans' attributes: - ref: client.address + requirement_level: recommended - ref: client.port + requirement_level: recommended - ref: network.peer.address + requirement_level: recommended - ref: network.peer.port requirement_level: recommended: If `network.peer.address` is set. - ref: network.transport + requirement_level: recommended - ref: network.type + requirement_level: recommended - id: rpc.grpc type: span @@ -75,12 +85,14 @@ groups: conditionally_required: If other than the default version (`1.0`) - ref: rpc.jsonrpc.request_id tag: jsonrpc-tech-specific + requirement_level: recommended - ref: rpc.jsonrpc.error_code tag: jsonrpc-tech-specific requirement_level: conditionally_required: If response is not successful. - ref: rpc.jsonrpc.error_message tag: jsonrpc-tech-specific + requirement_level: recommended - ref: rpc.method tag: jsonrpc-tech-specific requirement_level: required @@ -89,34 +101,18 @@ groups: RPC conventions for more information. - id: rpc.message - prefix: "message" # TODO: Change the prefix to rpc.message? + prefix: rpc.message type: event brief: "RPC received/sent message." attributes: - - id: type - type: - members: - - id: sent - value: "SENT" - stability: experimental - - id: received - value: "RECEIVED" - stability: experimental - stability: experimental - brief: "Whether this is a received or sent message." - - id: id - type: int - stability: experimental - brief: "MUST be calculated as two different counters starting from `1` one for sent messages and one for received message." - note: "This way we guarantee that the values will be consistent between different implementations." - - id: compressed_size - type: int - stability: experimental - brief: "Compressed size of the message in bytes." - - id: uncompressed_size - type: int - stability: experimental - brief: "Uncompressed size of the message in bytes." + - ref: rpc.message.type + requirement_level: recommended + - ref: rpc.message.id + requirement_level: recommended + - ref: rpc.message.compressed_size + requirement_level: recommended + - ref: rpc.message.uncompressed_size + requirement_level: recommended - id: rpc.connect_rpc type: span diff --git a/schema-next.yaml b/schema-next.yaml index 594dff735d..c36ffd7dc5 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -56,6 +56,15 @@ versions: type: process.paging.fault_type apply_to_metrics: - process.paging.faults + all: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/854 + - rename_attributes: + attribute_map: + message.type: rpc.message.type + message.id: rpc.message.id + message.compressed_size: rpc.message.compressed_size + message.uncompressed_size: rpc.message.uncompressed_size 1.24.0: metrics: