Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

move rpc.message to the registry #854

Merged
merged 17 commits into from
Apr 5, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 17 additions & 4 deletions docs/attributes-registry/rpc.md
Original file line number Diff line number Diff line change
Expand Up @@ -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` |
| `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`; `` |
| `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` |
| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [5] | `exampleMethod` |
| `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [6] | `myservice.EchoService` |
| `rpc.message.compressed_size` | int | Compressed size of the message in bytes. | |
| `rpc.message.id` | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [5] | |
| `rpc.message.type` | string | Whether this is a received or sent message. | `SENT` |
| `rpc.message.uncompressed_size` | int | Uncompressed size of the message in bytes. | |
| `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [6] | `exampleMethod` |
| `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [7] | `myservice.EchoService` |
| `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` |

**[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.
Expand All @@ -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:

Expand Down Expand Up @@ -79,6 +85,13 @@ RPC attributes are intended to be used in the context of events related to remot
| `15` | DATA_LOSS |
| `16` | UNAUTHENTICATED |

`rpc.message.type` MUST be one of the following:

| Value | Description |
|---|---|
| `SENT` | sent |
| `RECEIVED` | received |

`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 |
Expand Down
14 changes: 7 additions & 7 deletions docs/rpc/rpc-spans.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|---|---|---|---|---|
| `message.compressed_size` | int | Compressed size of the message in bytes. | | Recommended |
| `message.id` | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [1] | | Recommended |
| `message.type` | string | Whether this is a received or sent message. | `SENT` | Recommended |
| `message.uncompressed_size` | int | Uncompressed size of the message in bytes. | | Recommended |
| [`rpc.message.compressed_size`](../attributes-registry/rpc.md) | int | Compressed size of the message in bytes. | | Recommended |
| [`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 |
| [`rpc.message.type`](../attributes-registry/rpc.md) | string | Whether this is a received or sent message. | `SENT` | Recommended |
| [`rpc.message.uncompressed_size`](../attributes-registry/rpc.md) | int | Uncompressed size of the message in bytes. | | Recommended |

**[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 |
|---|---|
Expand Down
22 changes: 22 additions & 0 deletions model/registry/rpc.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -201,3 +201,25 @@ groups:
value: 'connect_rpc'
brief: 'Connect RPC'
stability: experimental
- id: message.type
lmolkova marked this conversation as resolved.
Show resolved Hide resolved
type:
members:
- id: sent
value: "SENT"
- id: received
value: "RECEIVED"
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."
28 changes: 5 additions & 23 deletions model/trace/rpc.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -89,32 +89,14 @@ 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"
- id: received
value: "RECEIVED"
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
trisch-me marked this conversation as resolved.
Show resolved Hide resolved
- ref: rpc.message.id
- ref: rpc.message.compressed_size
- ref: rpc.message.uncompressed_size

- id: rpc.connect_rpc
type: span
Expand Down
Loading