xref: /aosp_15_r20/external/grpc-grpc-java/services/src/main/proto/grpc/binlog/v1/binarylog.proto (revision e07d83d3ffcef9ecfc9f7f475418ec639ff0e5fe)
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