1# Binary Logging
2
3## Format
4
5The log format is described in [this proto file](/src/proto/grpc/binary_log/v1alpha/log.proto). It is intended that multiple parts of the call will be logged in separate files, and then correlated by analysis tools using the rpc\_id.
6
7## API
8
9The binary logger will be a separate library from gRPC, in each language that we support. The user will need to explicitly call into the library to generate logs. The library will provide the ability to log sending or receiving, as relevant, the following on both the client and the server:
10
11 - Initial metadata
12 - Messages
13 - Status with trailing metadata from the server
14 - Additional key/value pairs that are associated with a call but not sent over the wire
15
16The following is an example of what such an API could look like in C++:
17
18```c++
19// The context provides the method_name, deadline, peer, and metadata contents.
20// direction = CLIENT_SEND
21LogRequestHeaders(ClientContext context);
22// direction = SERVER_RECV
23LogRequestHeaders(ServerContext context);
24
25// The context provides the metadata contents
26// direction = CLIENT_RECV
27LogResponseHeaders(ClientContext context);
28// direction = SERVER_SEND
29LogResponseHeaders(ServerContext context);
30
31// The context provides the metadata contents
32// direction = CLIENT_RECV
33LogStatus(ClientContext context, grpc_status_code code, string details);
34// direction = SERVER_SEND
35LogStatus(ServerContext context, grpc_status_code code, string details);
36
37// The context provides the user data contents
38// direction = CLIENT_SEND
39LogUserData(ClientContext context);
40// direction = SERVER_SEND
41LogUserData(ServerContext context);
42
43// direction = CLIENT_SEND
44LogRequestMessage(ClientContext context, uint32_t length, T message);
45// direction = SERVER_RECV
46LogRequestMessage(ServerContext context, uint32_t length, T message);
47// direction = CLIENT_RECV
48LogResponseMessage(ClientContext context, uint32_t length, T message);
49// direction = SERVER_SEND
50LogResponseMessage(ServerContext context, uint32_t length, T message);
51```
52
53In all of those cases, the `rpc_id` is provided by the context, and each combination of method and context argument type implies a single direction, as noted in the comments.
54
55For the message log functions, the `length` argument indicates the length of the complete message, and the `message` argument may be only part of the complete message, stripped of sensitive material and/or shortened for efficiency.
56
57## Language differences
58
59In other languages, more or less data will need to be passed explicitly as separate arguments. In some languages, for example, the metadata will be separate from the context-like object and will need to be passed as a separate argument.
60