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.

Sign up for GitHub

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

Avoid using gRPC when generic RPC systems have same properties #1914

Merged
merged 5 commits into from
Sep 28, 2021
Merged

Avoid using gRPC when generic RPC systems have same properties #1914

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2b5bb41
Avoid using gRPC when generic RPC systems have same properties
bogdandrutu Sep 9, 2021
e3b234b
Update specification/trace/semantic_conventions/rpc.md
Sep 10, 2021
c23713d
Merge branch 'main' into grpcmessage
bogdandrutu Sep 15, 2021
56c004b
Merge branch 'main' into grpcmessage
bogdandrutu Sep 16, 2021
d11e995
Merge branch 'main' into grpcmessage
bogdandrutu Sep 28, 2021
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
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ release.

- Add InstrumentationLibrary to Sampler.ShouldSample.
([#1850](https://github.com/open-telemetry/opentelemetry-specification/pull/1850))
- Generalize the "message" event to apply to all RPC systems not just gRPC
([#1914](https://github.com/open-telemetry/opentelemetry-specification/pull/1914))

### Metrics

Expand Down
8 changes: 4 additions & 4 deletions semantic_conventions/trace/rpc.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ groups:
- id: rpc
prefix: rpc
brief: 'This document defines semantic conventions for remote procedure calls.'
events: [rpc.grpc.message]
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
events: [rpc.message]
attributes:
- id: system
type: string
Expand Down Expand Up @@ -142,10 +142,10 @@ groups:
note: >
This is always required for jsonrpc. See the note in the general
RPC conventions for more information.
- id: rpc.grpc.message
prefix: "message" # TODO: Change the prefix to rpc.grpc.message?
- id: rpc.message
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
prefix: "message" # TODO: Change the prefix to rpc.message?
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
type: event
brief: "gRPC received/sent message."
brief: "RPC received/sent message."
attributes:
- id: type
type:
Expand Down
55 changes: 27 additions & 28 deletions specification/trace/semantic_conventions/rpc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,11 @@ This document defines how to describe remote procedure calls
- [Span name](#span-name)
- [Attributes](#attributes)
- [Service name](#service-name)
- [Events](#events)
- [Distinction from HTTP spans](#distinction-from-http-spans)
- [gRPC](#grpc)
- [gRPC Attributes](#grpc-attributes)
- [gRPC Status](#grpc-status)
- [Events](#events)
- [JSON RPC](#json-rpc)
- [JSON RPC Attributes](#json-rpc-attributes)

Expand Down Expand Up @@ -95,6 +95,32 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service
[`service.name`]: ../../resource/semantic_conventions/README.md#service
[`peer.service`]: span-general.md#general-remote-service-attributes

### Events

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"`.

<!-- semconv rpc.message -->
| Attribute | Type | Description | Examples | Required |
|---|---|---|---|---|
| `message.type` | string | Whether this is a received or sent message. | `SENT` | No |
| `message.id` | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [1] | | No |
| `message.compressed_size` | int | Compressed size of the message in bytes. | | No |
| `message.uncompressed_size` | int | Uncompressed size of the message in bytes. | | No |

**[1]:** This way we guarantee that the values will be consistent between different implementations.

`message.type` MUST be one of the following:
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved

| Value | Description |
|---|---|
| `SENT` | sent |
| `RECEIVED` | received |
<!-- endsemconv -->

### Distinction from HTTP spans

HTTP calls can generally be represented using just [HTTP spans](./http.md).
Expand Down Expand Up @@ -143,33 +169,6 @@ For remote procedure calls via [gRPC][], additional conventions are described in

The [Span Status](../api.md#set-status) MUST be left unset for an `OK` gRPC status code, and set to `Error` for all others.

### Events

In the lifetime of a gRPC 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"`.

<!-- semconv rpc.grpc.message -->
| Attribute | Type | Description | Examples | Required |
|---|---|---|---|---|
| `message.type` | string | Whether this is a received or sent message. | `SENT` | No |
| `message.id` | int | MUST be calculated as two different counters starting from `1` one for sent messages and one for received message. [1] | | No |
| `message.compressed_size` | int | Compressed size of the message in bytes. | | No |
| `message.uncompressed_size` | int | Uncompressed size of the message in bytes. | | No |

**[1]:** This way we guarantee that the values will be consistent between different implementations.

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

| Value | Description |
|---|---|
| `SENT` | sent |
| `RECEIVED` | received |
<!-- endsemconv -->

## JSON RPC

Conventions specific to [JSON RPC](https://www.jsonrpc.org/).
Expand Down