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
19syntax = "proto3";
20
21package grpc.binarylog.v1;
22
23import "google/protobuf/duration.proto";
24import "google/protobuf/timestamp.proto";
25
26option go_package = "google.golang.org/grpc/binarylog/grpc_binarylog_v1";
27option java_multiple_files = true;
28option java_package = "io.grpc.binarylog.v1";
29option java_outer_classname = "BinaryLogProto";
30
31// Log entry we store in binary logs
32message 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
112message 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
132message ServerHeader {
133  // This contains only the metadata from the application.
134  Metadata metadata = 1;
135}
136
137message 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
154message 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.
183message Metadata {
184  repeated MetadataEntry entry = 1;
185}
186
187// A metadata key value pair
188message MetadataEntry {
189  string key = 1;
190  bytes value = 2;
191}
192
193// Address information
194message 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