From 7f3b8d66aa6f9014ccecd13c7613c9be734a8378 Mon Sep 17 00:00:00 2001 From: liudmila molkova Date: Wed, 17 Dec 2025 14:51:41 -0800 Subject: [PATCH 1/3] Separate RPC events from spans --- docs/rpc/rpc-events.md | 50 +++++++++++++++++++++++++++++++++++++++++ docs/rpc/rpc-spans.md | 51 ------------------------------------------ model/rpc/events.yaml | 19 ++++++++++++++++ model/rpc/spans.yaml | 21 ----------------- 4 files changed, 69 insertions(+), 72 deletions(-) create mode 100644 docs/rpc/rpc-events.md create mode 100644 model/rpc/events.yaml diff --git a/docs/rpc/rpc-events.md b/docs/rpc/rpc-events.md new file mode 100644 index 0000000000..d8e6c4d721 --- /dev/null +++ b/docs/rpc/rpc-events.md @@ -0,0 +1,50 @@ + + +# Semantic conventions for RPC events + +**Status**: [Development][DocumentStatus] + +This document defines events applicable in the context of remote procedure calls. + +## Message event + + + + + + +**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) | + + + + + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index c7d7b9331d..c5bc002bab 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -16,8 +16,6 @@ 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) @@ -343,59 +341,10 @@ and SHOULD be provided **at span creation time** (if provided at all): -### Events - -#### Message event - - - - - - -**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) | - - - - - ### 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 diff --git a/model/rpc/events.yaml b/model/rpc/events.yaml new file mode 100644 index 0000000000..3e31fe1dcc --- /dev/null +++ b/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 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 diff --git a/model/rpc/spans.yaml b/model/rpc/spans.yaml index e3fdc8f172..7b42a608a6 100644 --- a/model/rpc/spans.yaml +++ b/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 From 38e3597e8f63bb73f09c52c09e2e9b3f322b8f5a Mon Sep 17 00:00:00 2001 From: liudmila molkova Date: Wed, 17 Dec 2025 14:52:58 -0800 Subject: [PATCH 2/3] up --- docs/rpc/README.md | 1 + docs/rpc/rpc-spans.md | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rpc/README.md b/docs/rpc/README.md index 8a4afa2455..9334c0d02b 100644 --- a/docs/rpc/README.md +++ b/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: diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index c5bc002bab..6fdc6095a5 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -17,7 +17,6 @@ This document defines how to describe remote procedure calls - [RPC client span](#rpc-client-span) - [RPC server span](#rpc-server-span) - [Distinction from HTTP spans](#distinction-from-http-spans) -- [Semantic conventions for specific RPC technologies](#semantic-conventions-for-specific-rpc-technologies) From 5ed69ed3234ed4b2cd4e807db0655501a363039c Mon Sep 17 00:00:00 2001 From: liudmila molkova Date: Sat, 20 Dec 2025 17:55:00 -0800 Subject: [PATCH 3/3] add version blurb, don't record any messages for unary calls --- docs/rpc/rpc-events.md | 27 ++++++++++++++++++++++++++- model/rpc/events.yaml | 4 ++-- 2 files changed, 28 insertions(+), 3 deletions(-) diff --git a/docs/rpc/rpc-events.md b/docs/rpc/rpc-events.md index d8e6c4d721..70d2e7355e 100644 --- a/docs/rpc/rpc-events.md +++ b/docs/rpc/rpc-events.md @@ -8,6 +8,31 @@ linkTitle: Events 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 @@ -21,7 +46,7 @@ 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. +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:** diff --git a/model/rpc/events.yaml b/model/rpc/events.yaml index 3e31fe1dcc..70ab6fdc5e 100644 --- a/model/rpc/events.yaml +++ b/model/rpc/events.yaml @@ -6,8 +6,8 @@ groups: 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. + 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