1 // Copyright 2018 The gRPC Authors 2 // All rights reserved. 3 // 4 // Licensed under the Apache License, Version 2.0 (the "License"); 5 // you may not use this file except in compliance with the License. 6 // You may obtain a copy of the License at 7 // 8 // http://www.apache.org/licenses/LICENSE-2.0 9 // 10 // Unless required by applicable law or agreed to in writing, software 11 // distributed under the License is distributed on an "AS IS" BASIS, 12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 // See the License for the specific language governing permissions and 14 // limitations under the License. 15 16 // The canonical version of this proto can be found at 17 // https://github.com/grpc/grpc-proto/blob/master/grpc/binlog/v1/binarylog.proto 18 19 syntax = "proto3"; 20 21 package grpc.binarylog.v1; 22 23 import "google/protobuf/duration.proto"; 24 import "google/protobuf/timestamp.proto"; 25 26 option go_package = "google.golang.org/grpc/binarylog/grpc_binarylog_v1"; 27 option java_multiple_files = true; 28 option java_package = "io.grpc.binarylog.v1"; 29 option java_outer_classname = "BinaryLogProto"; 30 31 // Log entry we store in binary logs 32 message GrpcLogEntry { 33 // Enumerates the type of event 34 // Note the terminology is different from the RPC semantics 35 // definition, but the same meaning is expressed here. 36 enum EventType { 37 EVENT_TYPE_UNKNOWN = 0; 38 // Header sent from client to server 39 EVENT_TYPE_CLIENT_HEADER = 1; 40 // Header sent from server to client 41 EVENT_TYPE_SERVER_HEADER = 2; 42 // Message sent from client to server 43 EVENT_TYPE_CLIENT_MESSAGE = 3; 44 // Message sent from server to client 45 EVENT_TYPE_SERVER_MESSAGE = 4; 46 // A signal that client is done sending 47 EVENT_TYPE_CLIENT_HALF_CLOSE = 5; 48 // Trailer indicates the end of the RPC. 49 // On client side, this event means a trailer was either received 50 // from the network or the gRPC library locally generated a status 51 // to inform the application about a failure. 52 // On server side, this event means the server application requested 53 // to send a trailer. Note: EVENT_TYPE_CANCEL may still arrive after 54 // this due to races on server side. 55 EVENT_TYPE_SERVER_TRAILER = 6; 56 // A signal that the RPC is cancelled. On client side, this 57 // indicates the client application requests a cancellation. 58 // On server side, this indicates that cancellation was detected. 59 // Note: This marks the end of the RPC. Events may arrive after 60 // this due to races. For example, on client side a trailer 61 // may arrive even though the application requested to cancel the RPC. 62 EVENT_TYPE_CANCEL = 7; 63 } 64 65 // Enumerates the entity that generates the log entry 66 enum Logger { 67 LOGGER_UNKNOWN = 0; 68 LOGGER_CLIENT = 1; 69 LOGGER_SERVER = 2; 70 } 71 72 // The timestamp of the binary log message 73 google.protobuf.Timestamp timestamp = 1; 74 75 // Uniquely identifies a call. The value must not be 0 in order to disambiguate 76 // from an unset value. 77 // Each call may have several log entries, they will all have the same call_id. 78 // Nothing is guaranteed about their value other than they are unique across 79 // different RPCs in the same gRPC process. 80 uint64 call_id = 2; 81 82 // The entry sequence id for this call. The first GrpcLogEntry has a 83 // value of 1, to disambiguate from an unset value. The purpose of 84 // this field is to detect missing entries in environments where 85 // durability or ordering is not guaranteed. 86 uint64 sequence_id_within_call = 3; 87 88 EventType type = 4; 89 Logger logger = 5; // One of the above Logger enum 90 91 // The logger uses one of the following fields to record the payload, 92 // according to the type of the log entry. 93 oneof payload { 94 ClientHeader client_header = 6; 95 ServerHeader server_header = 7; 96 // Used by EVENT_TYPE_CLIENT_MESSAGE, EVENT_TYPE_SERVER_MESSAGE 97 Message message = 8; 98 Trailer trailer = 9; 99 } 100 101 // true if payload does not represent the full message or metadata. 102 bool payload_truncated = 10; 103 104 // Peer address information, will only be recorded on the first 105 // incoming event. On client side, peer is logged on 106 // EVENT_TYPE_SERVER_HEADER normally or EVENT_TYPE_SERVER_TRAILER in 107 // the case of trailers-only. On server side, peer is always 108 // logged on EVENT_TYPE_CLIENT_HEADER. 109 Address peer = 11; 110 }; 111 112 message ClientHeader { 113 // This contains only the metadata from the application. 114 Metadata metadata = 1; 115 116 // The name of the RPC method, which looks something like: 117 // /<service>/<method> 118 // Note the leading "/" character. 119 string method_name = 2; 120 121 // A single process may be used to run multiple virtual 122 // servers with different identities. 123 // The authority is the name of such a server identitiy. 124 // It is typically a portion of the URI in the form of 125 // <host> or <host>:<port> . 126 string authority = 3; 127 128 // the RPC timeout 129 google.protobuf.Duration timeout = 4; 130 } 131 132 message ServerHeader { 133 // This contains only the metadata from the application. 134 Metadata metadata = 1; 135 } 136 137 message Trailer { 138 // This contains only the metadata from the application. 139 Metadata metadata = 1; 140 141 // The gRPC status code. 142 uint32 status_code = 2; 143 144 // An original status message before any transport specific 145 // encoding. 146 string status_message = 3; 147 148 // The value of the 'grpc-status-details-bin' metadata key. If 149 // present, this is always an encoded 'google.rpc.Status' message. 150 bytes status_details = 4; 151 } 152 153 // Message payload, used by CLIENT_MESSAGE and SERVER_MESSAGE 154 message Message { 155 // Length of the message. It may not be the same as the length of the 156 // data field, as the logging payload can be truncated or omitted. 157 uint32 length = 1; 158 // May be truncated or omitted. 159 bytes data = 2; 160 } 161 162 // A list of metadata pairs, used in the payload of client header, 163 // server header, and server trailer. 164 // Implementations may omit some entries to honor the header limits 165 // of GRPC_BINARY_LOG_CONFIG. 166 // 167 // Header keys added by gRPC are omitted. To be more specific, 168 // implementations will not log the following entries, and this is 169 // not to be treated as a truncation: 170 // - entries handled by grpc that are not user visible, such as those 171 // that begin with 'grpc-' (with exception of grpc-trace-bin) 172 // or keys like 'lb-token' 173 // - transport specific entries, including but not limited to: 174 // ':path', ':authority', 'content-encoding', 'user-agent', 'te', etc 175 // - entries added for call credentials 176 // 177 // Implementations must always log grpc-trace-bin if it is present. 178 // Practically speaking it will only be visible on server side because 179 // grpc-trace-bin is managed by low level client side mechanisms 180 // inaccessible from the application level. On server side, the 181 // header is just a normal metadata key. 182 // The pair will not count towards the size limit. 183 message Metadata { 184 repeated MetadataEntry entry = 1; 185 } 186 187 // A metadata key value pair 188 message MetadataEntry { 189 string key = 1; 190 bytes value = 2; 191 } 192 193 // Address information 194 message Address { 195 enum Type { 196 TYPE_UNKNOWN = 0; 197 // address is in 1.2.3.4 form 198 TYPE_IPV4 = 1; 199 // address is in IPv6 canonical form (RFC5952 section 4) 200 // The scope is NOT included in the address string. 201 TYPE_IPV6 = 2; 202 // address is UDS string 203 TYPE_UNIX = 3; 204 }; 205 Type type = 1; 206 string address = 2; 207 // only for TYPE_IPV4 and TYPE_IPV6 208 uint32 ip_port = 3; 209 } 210