From 4d7046a85694fe8a95b1f09e1c11478d2c17ac04 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Wed, 5 Jun 2019 16:01:15 -0700 Subject: [PATCH] Grpc semantic convention documents move (#28) * move GRPC doc pieces * align table colums * OpenCensus -> OpenTelemetry and adjusted headers * addressed Yuri's feedback --- semantic-conventions.md | 58 +++++++++++++++++++++ work_in_progress/gRPC/gRPC.md | 73 --------------------------- work_in_progress/typedspans/README.md | 28 ++-------- 3 files changed, 63 insertions(+), 96 deletions(-) diff --git a/semantic-conventions.md b/semantic-conventions.md index c2708d771..a212c32eb 100644 --- a/semantic-conventions.md +++ b/semantic-conventions.md @@ -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" = , + "message.uncompressed_size" = +``` + +``` +-> [time], + "name" = "message", + "message.type" = "RECEIVED", + "message.id" = id + "message.compressed_size" = , + "message.uncompressed_size" = +``` + +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. diff --git a/work_in_progress/gRPC/gRPC.md b/work_in_progress/gRPC/gRPC.md index 143a275a9..ef4d0aefc 100644 --- a/work_in_progress/gRPC/gRPC.md +++ b/work_in_progress/gRPC/gRPC.md @@ -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" = , - "message.uncompressed_size" = -``` - -``` --> [time], - "name" = "message", - "message.type" = "RECEIVED", - "message.id" = id - "message.compressed_size" = , - "message.uncompressed_size" = -``` - -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. diff --git a/work_in_progress/typedspans/README.md b/work_in_progress/typedspans/README.md index 329bab7ac..8aa184cb8 100644 --- a/work_in_progress/typedspans/README.md +++ b/work_in_progress/typedspans/README.md @@ -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.