move rpc.message to the registry (#854)

Co-authored-by: Liudmila Molkova <[email protected]> Co-authored-by: Alexander Wert <[email protected]> Co-authored-by: Joao Grassi <[email protected]>
open-telemetry · Apr 5, 2024 · 262271f · 262271f
1 parent a307d19
commit 262271f
Show file tree

Hide file tree

Showing 7 changed files with 132 additions and 36 deletions.
diff --git a/.chloggen/rpc_registry.yaml 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
@@ -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
@@ -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.
 
-<!-- semconv rpc.message -->
-The event name MUST be `message`.
+<!-- semconv rpc.message(full) -->
+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
@@ -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
@@ -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
@@ -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
@@ -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: