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