open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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 2019-06-05 16:01:15 -07:00 committed by GitHub
parent 62988fdbf2
commit 4d7046a856
3 changed files with 63 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
semantic-conventions.md
View File

@ -47,3 +47,61 @@ follows:
| `peer.port` | Remote port. E.g., `80` (integer) | No | | `peer.port` | Remote port. E.g., `80` (integer) | No |
| `peer.service` | Remote service name. Can be database friendly name or `db.instance` | 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.

73
work_in_progress/gRPC/gRPC.md
View File

@ -1,25 +1,5 @@
# gRPC # 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
Propagation is how `SpanContext` is transmitted on the wire in an gRPC request. 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 and MUST extract a `SpanContext` from the gRPC metadata. Serialization format is
configurable. The default serialization format should be used is [W3C binary configurable. The default serialization format should be used is [W3C binary
trace context](https://w3c.github.io/trace-context-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.

28
work_in_progress/typedspans/README.md
View File

@ -77,42 +77,24 @@ Represents a database call.
These attributes are not covered in the [main spec](../semantic-conventions.md): These attributes are not covered in the [main spec](../semantic-conventions.md):
- Channel Type (e.g. TCP) - Channel Type (e.g. TCP)
- Rows Returned
- Roundtrips
- Arguments of db.statement
#### gRPC Client #### gRPC Client
Represents an outbound gRPC request. Represents an outbound gRPC request.
##### Attributes ##### 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 #### gRPC Server
Represents an inbound gRPC request. Represents an inbound gRPC request.
##### Detail Document
https://github.com/open-telemetry/opentelemetry-specification/blob/master/work_in_progress/gRPC/gRPC.md
##### Attributes ##### Attributes
- Message Id
- Message Compressed Size
- Message Uncompressed Size
#### gRPC Client These attributes are not covered in the [main spec](../semantic-conventions.md):
Represents an inbound gRPC request.
##### Detail Document - Channel Type (e.g. TCP)
https://github.com/open-telemetry/opentelemetry-specification/blob/master/work_in_progress/gRPC/gRPC.md
##### Attributes
- Message Id
- Message Compressed Size
- Message Uncompressed Size
#### Remoting Client #### Remoting Client
Represents an outbound RPC request. Represents an outbound RPC request.