Separate RPC events from spans

docs/rpc/README.md

@@ -38,6 +38,7 @@ Semantic conventions for RPC are defined for the following signals:
 
 * [RPC Spans](rpc-spans.md): Semantic Conventions for RPC client and server *spans*.
 * [RPC Metrics](rpc-metrics.md): Semantic Conventions for RPC *metrics*.
+* [RPC Events](rpc-events.md): Semantic Conventions for RPC *events*.
 
 Technology specific semantic conventions are defined for the following RPC systems:
 

docs/rpc/rpc-events.md

@@ -0,0 +1,75 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Events
+--->
+
+# Semantic conventions for RPC events
+
+**Status**: [Development][DocumentStatus]
+
+This document defines events applicable in the context of remote procedure calls.
+
+> [!IMPORTANT]
+> Existing RPC instrumentations that are using
+> [v1.37.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.37.0/docs/rpc/rpc-spans.md#events)
+> (or prior):
+>
+> * SHOULD NOT change the version of the RPC conventions that they emit by
+>   default in their existing major version. Conventions include (but are not
+>   limited to) attributes, metric and span names, and unit of measure.
+> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
+>   in their existing major version as a comma-separated list of category-specific values
+>   (e.g., http, databases, rpc). The list of values includes:
+>   * `rpc` - emit the stable RPC conventions, and stop emitting
+>     the experimental RPC conventions that the instrumentation emitted
+>     previously.
+>   * `rpc/dup` - emit both the experimental and stable RPC conventions,
+>     allowing for a phased rollout of the stable semantic conventions.
+>   * The default behavior (in the absence of one of these values) is to continue
+>     emitting whatever version of the old experimental RPC conventions
+>     the instrumentation was emitting previously.
+>   * Note: `rpc/dup` has higher precedence than `rpc` in case both values are present
+> * SHOULD maintain (security patching at a minimum) their existing major version
+>   for at least six months after it starts emitting both sets of conventions.
+> * MAY drop the environment variable in their next major version and emit only
+>   the stable RPC conventions.
+
+## Message event
+
+<!-- semconv event.rpc.message -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+
+**Status:** ![Development](https://img.shields.io/badge/-development-blue)
+
+The event name MUST be `rpc.message`.
+
+Describes a message sent or received within the context of an RPC call.
+
+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 message events SHOULD NOT be recorded.
+
+**Attributes:**
+
+| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
+| --- | --- | --- | --- | --- | --- |
+| [`rpc.message.compressed_size`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | Compressed size of the message in bytes. | |
+| [`rpc.message.id`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [1] | |
+| [`rpc.message.type`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Whether this is a received or sent message. | `SENT`; `RECEIVED` |
+| [`rpc.message.uncompressed_size`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | Uncompressed size of the message in bytes. | |
+
+**[1] `rpc.message.id`:** This way we guarantee that the values will be consistent between different implementations.
+
+---
+
+`rpc.message.type` 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 |
+| --- | --- | --- |
+| `RECEIVED` | received | ![Development](https://img.shields.io/badge/-development-blue) |
+| `SENT` | sent | ![Development](https://img.shields.io/badge/-development-blue) |
+
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

docs/rpc/rpc-spans.md

@@ -16,10 +16,7 @@ This document defines how to describe remote procedure calls
   - [Service name](#service-name)
   - [RPC client span](#rpc-client-span)
   - [RPC server span](#rpc-server-span)
-  - [Events](#events)
-    - [Message event](#message-event)
   - [Distinction from HTTP spans](#distinction-from-http-spans)
-- [Semantic conventions for specific RPC technologies](#semantic-conventions-for-specific-rpc-technologies)
 
 <!-- tocstop -->
 
@@ -343,59 +340,10 @@ and SHOULD be provided **at span creation time** (if provided at all):
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
-### Events
-
-#### Message event
-
-<!-- semconv event.rpc.message -->
-<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
-<!-- see templates/registry/markdown/snippet.md.j2 -->
-<!-- prettier-ignore-start -->
-
-**Status:** ![Development](https://img.shields.io/badge/-development-blue)
-
-The event name MUST be `rpc.message`.
-
-Describes a message sent or received within the context of an RPC call.
-
-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.
-
-**Attributes:**
-
-| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
-| --- | --- | --- | --- | --- | --- |
-| [`rpc.message.compressed_size`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | Compressed size of the message in bytes. | |
-| [`rpc.message.id`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [1] | |
-| [`rpc.message.type`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Whether this is a received or sent message. | `SENT`; `RECEIVED` |
-| [`rpc.message.uncompressed_size`](/docs/registry/attributes/rpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | int | Uncompressed size of the message in bytes. | |
-
-**[1] `rpc.message.id`:** This way we guarantee that the values will be consistent between different implementations.
-
----
-
-`rpc.message.type` 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 |
-| --- | --- | --- |
-| `RECEIVED` | received | ![Development](https://img.shields.io/badge/-development-blue) |
-| `SENT` | sent | ![Development](https://img.shields.io/badge/-development-blue) |
-
-<!-- prettier-ignore-end -->
-<!-- END AUTOGENERATED TEXT -->
-<!-- endsemconv -->
-
 ### Distinction from HTTP spans
 
 HTTP calls can generally be represented using just [HTTP spans](/docs/http/http-spans.md).
 If they address a particular remote service and method known to the caller, i.e., when it is a remote procedure call transported over HTTP, the `rpc.*` attributes might be added additionally on that span, or in a separate RPC span that is a parent of the transporting HTTP call.
 Note that *method* in this context is about the called remote procedure and *not* the HTTP verb (GET, POST, etc.).
 
-## Semantic conventions for specific RPC technologies
-
-More specific Semantic Conventions are defined for the following RPC technologies:
-
-* [Connect](connect-rpc.md): Semantic Conventions for *Connect RPC*.
-* [gRPC](grpc.md): Semantic Conventions for *gRPC*.
-* [JSON-RPC](json-rpc.md): Semantic Conventions for *JSON-RPC*.
-
 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

model/rpc/events.yaml

@@ -0,0 +1,19 @@
+groups:
+  - id: event.rpc.message
+    type: event
+    stability: development
+    name: rpc.message
+    brief: Describes a message sent or received within the context of an RPC call.
+    note: >
+      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 message
+      events SHOULD NOT be recorded.
+    attributes:
+      - 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

model/rpc/spans.yaml

@@ -63,7 +63,6 @@ groups:
       document for details on how to record span status.
     extends: rpc
     span_kind: client
-    events: [rpc.message]
     attributes:
       - ref: rpc.system.name
         requirement_level: required
@@ -77,7 +76,6 @@ groups:
     extends: rpc_service.server
     span_kind: server
     brief: This span represents an incoming Remote Procedure Call (RPC).
-    events: [rpc.message]
     note: |
       RPC server spans SHOULD cover the entire server-side lifecycle of an RPC,
       starting when the request is received and ending when the response is sent
@@ -298,22 +296,3 @@ groups:
           All JSON RPC error codes SHOULD be considered errors.
         requirement_level:
           conditionally_required: when available
-
-  - id: event.rpc.message
-    type: event
-    stability: development
-    name: rpc.message
-    brief: Describes a message sent or received within the context of an RPC call.
-    note: >
-      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.
-    attributes:
-      - 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