Add initial documentation for gRPC trace. (#98)

* Add initial documentation for gRPC trace.

* Address comments.

* Clarify MessageId generation.

Author: Bogdan Drutu

trace/HTTP.md

@@ -1,19 +1,18 @@
-# HTTP
+# HTTP Trace
 
 This document explains tracing of HTTP requests with OpenCensus.
 
 ## Spans
 
-Implementations MUST create a span for outgoing requests at the
-client and a span for incoming requests at the server.
+Implementations MUST create a span for outgoing requests at the client and a span for incoming 
+requests at the server.
 
 Span name is formatted as:
 
 * /$path for outgoing requests.
 * /($path|$route) for incoming requests.
 
-If route cannot be determined, path is used to name the
-the span for outgoing requests.
+If route cannot be determined, path is used to name the the span for outgoing requests.
 
 Port MUST be omitted if it is 80 or 443.
 
@@ -28,35 +27,31 @@ incoming requests should be a span kind of SERVER.
 
 ## Propagation
 
-Propagation is how SpanContext is transmitted on the wire
-in an HTTP request.
+Propagation is how SpanContext is transmitted on the wire in an HTTP request.
 
-Implementations MUST allow users to set their own propagation
-format and MUST provide an implementation for B3 at least.
+Implementations MUST allow users to set their own propagation format and MUST provide an 
+implementation for B3 at least.
 
 If user doesn't set any propagation methods explicitly, B3 is used.
 
-The propagation method SHOULD modify a request object to insert
-a SpanContext or SHOULD be able to extract a SpanContext from a
-request object.
+The propagation method SHOULD modify a request object to insert a SpanContext or SHOULD be able 
+to extract a SpanContext from a request object.
 
 ## Status
 
-Implementations MUST set status if HTTP request or response
-is not successful (e.g. not 2xx). In redirection case, if
-the client doesn't have autoredirection support, request
-should be considered successful.
+Implementations MUST set status if HTTP request or response is not successful (e.g. not 2xx). In 
+redirection case, if the client doesn't have autoredirection support, request should be 
+considered successful.
 
-Set status code to UNKNOWN (2) if the reason cannot be inferred
-at the callsite or from the HTTP status code.
+Set status code to UNKNOWN (2) if the reason cannot be inferred at the callsite or from the HTTP 
+status code.
 
-Don't set the status message if the reason can be inferred at
-the callsite of from the HTTP status code.
+Don't set the status message if the reason can be inferred at the callsite of from the HTTP 
+status code.
 
 ## Message events
 
-In the lifetime of an incoming and outgoing request, the following
-message events SHOULD be created:
+In the lifetime of an incoming and outgoing request, the following message events SHOULD be created:
 
 * A message event for the request body size if/when determined.
 * A message event for the response size if/when determined.
@@ -75,9 +70,8 @@ Implementations SHOULD create message event when response size is determined.
 
 ## Attributes
 
-Implementations SHOULD set the following attributes on the client
-and server spans. For a server, request represents the incoming request.
-For a client, request represents the outgoing request.
+Implementations SHOULD set the following attributes on the client and server spans. For a server,
+ request represents the incoming request. For a client, request represents the outgoing request.
 
 All attributes are optional.
 
@@ -90,9 +84,8 @@ All attributes are optional.
 | "http.user_agent"         | Request user-agent          | "HTTPClient/1.2"                |
 | "http.status_code"        | Response status code        | 200                             |
 
-Exporters should always export the collected attributes.
-Exporters should map the collected attributes to backend's
-known attributes/labels.
+Exporters should always export the collected attributes. Exporters should map the collected 
+attributes to backend's known attributes/labels.
 
 The following table summarizes how OpenCensus attributes maps to the
 known attributes/labels on supported tracing backends.

trace/README.md

@@ -7,5 +7,6 @@ describes the key types and the overall behavior.
 * [TraceConfig](TraceConfig.md)
 
 ## Utils
+* [gRPC integration](gRPC.md): document about how to instrument gRPC framework.
 * [HTTP integration](HTTP.md): document about how to instrument http frameworks.
 * [Sampling logic](Sampling.md): document about how sampling works.

trace/gRPC.md

@@ -0,0 +1,55 @@
+# gRPC Trace
+
+This document explains tracing of gRPC requests with OpenCensus.
+
+## Spans
+
+Implementations MUST create a span, when the gRPC call starts, for the client and a span for the 
+server.
+
+Span name is formatted as (also known as full gRPC method name):
+
+* $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.
+
+For backends that does not support Span.Kind, the exported span names can be prefixed with `Sent.`
+(for CLIENT kind) and `Recv.` (for SERVER kind).
+
+## Propagation
+
+Propagation is how SpanContext is transmitted on the wire in an gRPC request.
+
+The propagation MUST inject a SpanContext (as a gRPC metadata `grpc-trace-bin`) and MUST extract 
+a SpanContext from the gRPC metadata. The serialization format is defined
+[here](../encodings/BinaryEncoding.md).
+
+## 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).
+
+## Message events
+
+In the lifetime of a gRPC stream, the following message events SHOULD be created:
+
+* A message event for each message sent/received on client and server spans.
+
+```
+-> [time], MessageEventTypeSent, MessageId, UncompressedByteSize, CompressedByteSize
+```
+
+```
+-> [time], MessageEventTypeRecv, MessageId, UncompressedByteSize, CompressedByteSize
+```
+
+The `MessageId` 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.