1 # Binary Logging 2 3 ## Format 4 5 The 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 9 The 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 16 The 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 21 LogRequestHeaders(ClientContext context); 22 // direction = SERVER_RECV 23 LogRequestHeaders(ServerContext context); 24 25 // The context provides the metadata contents 26 // direction = CLIENT_RECV 27 LogResponseHeaders(ClientContext context); 28 // direction = SERVER_SEND 29 LogResponseHeaders(ServerContext context); 30 31 // The context provides the metadata contents 32 // direction = CLIENT_RECV 33 LogStatus(ClientContext context, grpc_status_code code, string details); 34 // direction = SERVER_SEND 35 LogStatus(ServerContext context, grpc_status_code code, string details); 36 37 // The context provides the user data contents 38 // direction = CLIENT_SEND 39 LogUserData(ClientContext context); 40 // direction = SERVER_SEND 41 LogUserData(ServerContext context); 42 43 // direction = CLIENT_SEND 44 LogRequestMessage(ClientContext context, uint32_t length, T message); 45 // direction = SERVER_RECV 46 LogRequestMessage(ServerContext context, uint32_t length, T message); 47 // direction = CLIENT_RECV 48 LogResponseMessage(ClientContext context, uint32_t length, T message); 49 // direction = SERVER_SEND 50 LogResponseMessage(ServerContext context, uint32_t length, T message); 51 ``` 52 53 In 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 55 For 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 59 In 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
