Grpc semantic convention documents move (#28)
* move GRPC doc pieces * align table colums * OpenCensus -> OpenTelemetry and adjusted headers * addressed Yuri's feedback
This commit is contained in:
Sergey Kanzhelev
GitHub
parent
62988fdbf2
commit
4d7046a856
|
|
@ -47,3 +47,61 @@ follows:
|
|||
| `peer.port` | Remote port. E.g., `80` (integer) | No |
|
||||
| `peer.service` | Remote service name. Can be database friendly name or `db.instance` | No |
|
||||
|
||||
## gRPC
|
||||
|
||||
Implementations MUST create a span, when the gRPC call starts, one for
|
||||
client-side and one for server-side. Outgoing requests should be a span `kind`
|
||||
of `CLIENT` and incoming requests should be a span `kind` of `SERVER`.
|
||||
|
||||
Span `name` MUST be full gRPC method name formatted as:
|
||||
|
||||
```
|
||||
$package.$service/$method
|
||||
```
|
||||
|
||||
Examples of span name: `grpc.test.EchoService/Echo`.
|
||||
|
||||
### Attributes
|
||||
|
||||
| Attribute name | Notes and examples | Required? |
|
||||
| -------------- | ------------------------------------------------------------ | --------- |
|
||||
| `component` | Declares that this is a grpc component. Value MUST be `grpc` | Yes |
|
||||
|
||||
`peer.*` attributes MUST define service name as `peer.service`, host as
|
||||
`peer.hostname` and port as `peer.port`.
|
||||
|
||||
### Status
|
||||
|
||||
Implementations MUST set status which MUST be the same as the gRPC client/server
|
||||
status. The mapping between gRPC canonical codes and OpenTelemetry status codes
|
||||
is 1:1 as OpenTelemetry canonical codes is just a snapshot of grpc codes which
|
||||
can be found [here](https://github.com/grpc/grpc-go/blob/master/codes/codes.go).
|
||||
|
||||
### Events
|
||||
|
||||
In the lifetime of a gRPC stream, an event for each message sent/received on
|
||||
client and server spans SHOULD be created with the following attributes:
|
||||
|
||||
```
|
||||
-> [time],
|
||||
"name" = "message",
|
||||
"message.type" = "SENT",
|
||||
"message.id" = id
|
||||
"message.compressed_size" = <compressed size in bytes>,
|
||||
"message.uncompressed_size" = <uncompressed size in bytes>
|
||||
```
|
||||
|
||||
```
|
||||
-> [time],
|
||||
"name" = "message",
|
||||
"message.type" = "RECEIVED",
|
||||
"message.id" = id
|
||||
"message.compressed_size" = <compressed size in bytes>,
|
||||
"message.uncompressed_size" = <uncompressed size in bytes>
|
||||
```
|
||||
|
||||
The `message.id` MUST be calculated as two different counters starting from `1`
|
||||
one for sent messages and one for received message. This way we guarantee that
|
||||
the values will be consistent between different implementations. In case of
|
||||
unary calls only one sent and one received message will be recorded for both
|
||||
client and server spans.
|
||||
|
|
|
|||
|
|
@ -1,25 +1,5 @@
|
|||
# gRPC
|
||||
|
||||
This document explains tracing of gRPC requests with OpenConsensus.
|
||||
|
||||
## Spans
|
||||
|
||||
Implementations MUST create a span, when the gRPC call starts, for the client
|
||||
and a span for the server.
|
||||
|
||||
Span `name` MUST be full gRPC method name formatted as:
|
||||
|
||||
```
|
||||
$package.$service/$method
|
||||
```
|
||||
|
||||
Examples of span names:
|
||||
|
||||
- `grpc.test.EchoService/Echo`
|
||||
|
||||
Outgoing requests should be a span `kind` of `CLIENT` and incoming requests
|
||||
should be a span `kind` of `SERVER`.
|
||||
|
||||
## Propagation
|
||||
|
||||
Propagation is how `SpanContext` is transmitted on the wire in an gRPC request.
|
||||
|
|
@ -30,56 +10,3 @@ The propagation MUST inject a `SpanContext` as a gRPC metadata `grpc-trace-bin`
|
|||
and MUST extract a `SpanContext` from the gRPC metadata. Serialization format is
|
||||
configurable. The default serialization format should be used is [W3C binary
|
||||
trace context](https://w3c.github.io/trace-context-binary/).
|
||||
|
||||
## Attributes
|
||||
|
||||
|
||||
**TODO: `type` is not implemented today in existing integrations. Need to track it**
|
||||
**TODO: should we include `host`, `uri` or those should be reported as `peer`?**
|
||||
**TODO: agree that `component` from OpenTracing is being replaced with `type` as
|
||||
a better name.**
|
||||
|
||||
| Attribute name | Description | Type |Example value |
|
||||
|---------------------------|--------------------------------|--------|---------------------------|
|
||||
| "type" | Type of the client/server span | string | `grpc` |
|
||||
|
||||
## Status
|
||||
|
||||
Implementations MUST set status which should be the same as the gRPC
|
||||
client/server status. The mapping between gRPC canonical codes and OpenCensus
|
||||
status codes can be found
|
||||
[here](https://github.com/grpc/grpc-go/blob/master/codes/codes.go).
|
||||
|
||||
## Events
|
||||
|
||||
In the lifetime of a gRPC stream, the following events SHOULD be created:
|
||||
|
||||
- An event for each message sent/received on client and server spans.
|
||||
|
||||
[Message
|
||||
event](../../contrib/src/main/java/opentelemetry/contrib/trace/MessageEvent.java)
|
||||
should be used as a name of event.
|
||||
|
||||
```
|
||||
-> [time],
|
||||
"name" = "message",
|
||||
"message.type" = "SENT",
|
||||
"message.id" = id
|
||||
"message.compressed_size" = <compressed size in bytes>,
|
||||
"message.uncompressed_size" = <uncompressed size in bytes>
|
||||
```
|
||||
|
||||
```
|
||||
-> [time],
|
||||
"name" = "message",
|
||||
"message.type" = "RECEIVED",
|
||||
"message.id" = id
|
||||
"message.compressed_size" = <compressed size in bytes>,
|
||||
"message.uncompressed_size" = <uncompressed size in bytes>
|
||||
```
|
||||
|
||||
The `message.id` MUST be calculated as two different counters starting from `1`
|
||||
one for sent messages and one for received message. This way we guarantee that
|
||||
the values will be consistent between different implementations. In case of
|
||||
unary calls only one sent and one received message will be recorded for both
|
||||
client and server spans.
|
||||
|
|
|
|||
|
|
@ -77,42 +77,24 @@ Represents a database call.
|
|||
These attributes are not covered in the [main spec](../semantic-conventions.md):
|
||||
|
||||
- Channel Type (e.g. TCP)
|
||||
- Rows Returned
|
||||
- Roundtrips
|
||||
- Arguments of db.statement
|
||||
|
||||
#### gRPC Client
|
||||
Represents an outbound gRPC request.
|
||||
|
||||
##### Attributes
|
||||
- Service Endpoint
|
||||
- Channel Type (e.g. TCP)
|
||||
- Channel Endpoint
|
||||
- Service Name
|
||||
- Service Method
|
||||
|
||||
These attributes are not covered in the [main spec](../semantic-conventions.md):
|
||||
|
||||
- Channel Type (e.g. TCP)
|
||||
|
||||
#### gRPC Server
|
||||
Represents an inbound gRPC request.
|
||||
|
||||
##### Detail Document
|
||||
https://github.com/open-telemetry/opentelemetry-specification/blob/master/work_in_progress/gRPC/gRPC.md
|
||||
|
||||
##### Attributes
|
||||
- Message Id
|
||||
- Message Compressed Size
|
||||
- Message Uncompressed Size
|
||||
|
||||
#### gRPC Client
|
||||
Represents an inbound gRPC request.
|
||||
These attributes are not covered in the [main spec](../semantic-conventions.md):
|
||||
|
||||
##### Detail Document
|
||||
https://github.com/open-telemetry/opentelemetry-specification/blob/master/work_in_progress/gRPC/gRPC.md
|
||||
|
||||
##### Attributes
|
||||
- Message Id
|
||||
- Message Compressed Size
|
||||
- Message Uncompressed Size
|
||||
- Channel Type (e.g. TCP)
|
||||
|
||||
#### Remoting Client
|
||||
Represents an outbound RPC request.
|
||||
|
|
|
|||
Loading…
Reference in New Issue