Merge pull request #5189 from murgatroid99/binary_logging

Binary logging

doc/binary-logging.md

+# Binary Logging
+
+## Format
+
+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.
+
+## API
+
+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:
+
+ - Initial metadata
+ - Messages
+ - Status with trailing metadata from the server
+ - Additional key/value pairs that are associated with a call but not sent over the wire
+
+The following is an example of what such an API could look like in C++:
+
+```c++
+// The context provides the method_name, deadline, peer, and metadata contents.
+// direction = CLIENT_SEND
+LogRequestHeaders(ClientContext context);
+// direction = SERVER_RECV
+LogRequestHeaders(ServerContext context);
+
+// The context provides the metadata contents
+// direction = CLIENT_RECV
+LogResponseHeaders(ClientContext context);
+// direction = SERVER_SEND
+LogResponseHeaders(ServerContext context);
+
+// The context provides the metadata contents
+// direction = CLIENT_RECV
+LogStatus(ClientContext context, grpc_status_code code, string details);
+// direction = SERVER_SEND
+LogStatus(ServerContext context, grpc_status_code code, string details);
+
+// The context provides the user data contents
+// direction = CLIENT_SEND
+LogUserData(ClientContext context);
+// direction = SERVER_SEND
+LogUserData(ServerContext context);
+
+// direction = CLIENT_SEND
+LogRequestMessage(ClientContext context, uint32_t length, T message);
+// direction = SERVER_RECV
+LogRequestMessage(ServerContext context, uint32_t length, T message);
+// direction = CLIENT_RECV
+LogResponseMessage(ClientContext context, uint32_t length, T message);
+// direction = SERVER_SEND
+LogResponseMessage(ServerContext context, uint32_t length, T message);
+```
+
+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.
+
+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.
+
+## Language differences
+
+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.

src/proto/grpc/binary_log/v1alpha/log.proto

+// Copyright 2016, Google Inc.
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are
+// met:
+//
+//     * Redistributions of source code must retain the above copyright
+// notice, this list of conditions and the following disclaimer.
+//     * Redistributions in binary form must reproduce the above
+// copyright notice, this list of conditions and the following disclaimer
+// in the documentation and/or other materials provided with the
+// distribution.
+//     * Neither the name of Google Inc. nor the names of its
+// contributors may be used to endorse or promote products derived from
+// this software without specific prior written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+syntax = "proto3";
+
+import "google/protobuf/timestamp.proto"
+
+package grpc.binary_log.v1alpha;
+
+enum Direction {
+  SERVER_SEND;
+  SERVER_RECV;
+  CLIENT_SEND;
+  CLIENT_RECV;
+}
+
+message KeyValuePair {
+  string key;
+  string value;
+}
+
+// Any sort of metadata that may be sent in either direction during a call
+message Metadata {
+  // Cryptographically unique identifier, generated on the client and sent
+  // to the server.
+  uint64 rpc_id = 1;
+  // Timestamp of logging the metadata
+  google.protobuf.Timestamp timestamp = 2;
+  Direction direction = 3;
+  // The actual metadata that is being sent
+  repeated KeyValuePair metadata = 4;
+
+  // Initial metadata sent by the client to initiate a request
+  message ClientInitialMetadata {
+    // The full method name that is being called
+    string method_name = 1;
+    // The call's deadline
+    google.protobuf.Timestamp deadline = 2;
+    // The address of the connected peer
+    string peer = 3;
+  }
+
+  // Arbitrary key/value pairs specified by the user that are not sent over
+  // the network but are nonetheless useful to log
+  message UserData {
+  }
+
+  // Initial metadata response sent by the server after accepting the request
+  message ServerInitialMetadata {
+  }
+
+  // Status sent by the server when closing the call on the server side
+  message ServerStatus {
+    // The status code
+    uint32 code = 1;
+    // The status details
+    string details = 2;
+  }
+
+  oneof kind {
+    ClientInitialMetadata client_initial_metadata = 5;
+    UserData user_data = 6;
+    ServerInitialMetadata server_initial_metadata = 7;
+    ServerStatus server_status = 8;
+  }
+}
+
+// A message that is sent during a call
+message Message {
+  // Cryptographically unique identifier, generated on the client and sent
+  // to the server.
+  uint64 rpc_id = 1;
+  // The sequence number of the message. Messages sent by the client and by the
+  // server should have independently incrementing sequence numbers.
+  uint32 sequence_number = 2;
+  Direction direction = 3;
+  // The length of the complete message.
+  uint32 length = 4;
+  // The contents of the message. May be a prefix instead of the complete
+  // message.
+  bytes data = 5;
+}
\ No newline at end of file