/
common.proto
310 lines (252 loc) · 13.7 KB
/
common.proto
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
syntax = "proto3";
package envoy.config.tap.v3;
import "envoy/config/common/matcher/v3/matcher.proto";
import "envoy/config/core/v3/base.proto";
import "envoy/config/core/v3/grpc_service.proto";
import "envoy/config/route/v3/route_components.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/wrappers.proto";
import "envoy/annotations/deprecation.proto";
import "udpa/annotations/status.proto";
import "udpa/annotations/versioning.proto";
import "validate/validate.proto";
option java_package = "io.envoyproxy.envoy.config.tap.v3";
option java_outer_classname = "CommonProto";
option java_multiple_files = true;
option go_package = "github.com/envoyproxy/go-control-plane/envoy/config/tap/v3;tapv3";
option (udpa.annotations.file_status).package_version_status = ACTIVE;
// [#protodoc-title: Tap common configuration]
// Tap configuration.
message TapConfig {
// [#comment:TODO(mattklein123): Rate limiting]
option (udpa.annotations.versioning).previous_message_type =
"envoy.service.tap.v2alpha.TapConfig";
// The match configuration. If the configuration matches the data source being tapped, a tap will
// occur, with the result written to the configured output.
// Exactly one of :ref:`match <envoy_v3_api_field_config.tap.v3.TapConfig.match>` and
// :ref:`match_config <envoy_v3_api_field_config.tap.v3.TapConfig.match_config>` must be set. If both
// are set, the :ref:`match <envoy_v3_api_field_config.tap.v3.TapConfig.match>` will be used.
MatchPredicate match_config = 1
[deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
// The match configuration. If the configuration matches the data source being tapped, a tap will
// occur, with the result written to the configured output.
// Exactly one of :ref:`match <envoy_v3_api_field_config.tap.v3.TapConfig.match>` and
// :ref:`match_config <envoy_v3_api_field_config.tap.v3.TapConfig.match_config>` must be set. If both
// are set, the :ref:`match <envoy_v3_api_field_config.tap.v3.TapConfig.match>` will be used.
common.matcher.v3.MatchPredicate match = 4;
// The tap output configuration. If a match configuration matches a data source being tapped,
// a tap will occur and the data will be written to the configured output.
OutputConfig output_config = 2 [(validate.rules).message = {required: true}];
// [#not-implemented-hide:] Specify if Tap matching is enabled. The % of requests\connections for
// which the tap matching is enabled. When not enabled, the request\connection will not be
// recorded.
//
// .. note::
//
// This field defaults to 100/:ref:`HUNDRED
// <envoy_v3_api_enum_type.v3.FractionalPercent.DenominatorType>`.
core.v3.RuntimeFractionalPercent tap_enabled = 3;
}
// Tap match configuration. This is a recursive structure which allows complex nested match
// configurations to be built using various logical operators.
// [#next-free-field: 11]
message MatchPredicate {
option (udpa.annotations.versioning).previous_message_type =
"envoy.service.tap.v2alpha.MatchPredicate";
// A set of match configurations used for logical operations.
message MatchSet {
option (udpa.annotations.versioning).previous_message_type =
"envoy.service.tap.v2alpha.MatchPredicate.MatchSet";
// The list of rules that make up the set.
repeated MatchPredicate rules = 1 [(validate.rules).repeated = {min_items: 2}];
}
oneof rule {
option (validate.required) = true;
// A set that describes a logical OR. If any member of the set matches, the match configuration
// matches.
MatchSet or_match = 1;
// A set that describes a logical AND. If all members of the set match, the match configuration
// matches.
MatchSet and_match = 2;
// A negation match. The match configuration will match if the negated match condition matches.
MatchPredicate not_match = 3;
// The match configuration will always match.
bool any_match = 4 [(validate.rules).bool = {const: true}];
// HTTP request headers match configuration.
HttpHeadersMatch http_request_headers_match = 5;
// HTTP request trailers match configuration.
HttpHeadersMatch http_request_trailers_match = 6;
// HTTP response headers match configuration.
HttpHeadersMatch http_response_headers_match = 7;
// HTTP response trailers match configuration.
HttpHeadersMatch http_response_trailers_match = 8;
// HTTP request generic body match configuration.
HttpGenericBodyMatch http_request_generic_body_match = 9;
// HTTP response generic body match configuration.
HttpGenericBodyMatch http_response_generic_body_match = 10;
}
}
// HTTP headers match configuration.
message HttpHeadersMatch {
option (udpa.annotations.versioning).previous_message_type =
"envoy.service.tap.v2alpha.HttpHeadersMatch";
// HTTP headers to match.
repeated route.v3.HeaderMatcher headers = 1;
}
// HTTP generic body match configuration.
// List of text strings and hex strings to be located in HTTP body.
// All specified strings must be found in the HTTP body for positive match.
// The search may be limited to specified number of bytes from the body start.
//
// .. attention::
//
// Searching for patterns in HTTP body is potentially cpu intensive. For each specified pattern, http body is scanned byte by byte to find a match.
// If multiple patterns are specified, the process is repeated for each pattern. If location of a pattern is known, ``bytes_limit`` should be specified
// to scan only part of the http body.
message HttpGenericBodyMatch {
message GenericTextMatch {
oneof rule {
option (validate.required) = true;
// Text string to be located in HTTP body.
string string_match = 1 [(validate.rules).string = {min_len: 1}];
// Sequence of bytes to be located in HTTP body.
bytes binary_match = 2 [(validate.rules).bytes = {min_len: 1}];
}
}
// Limits search to specified number of bytes - default zero (no limit - match entire captured buffer).
uint32 bytes_limit = 1;
// List of patterns to match.
repeated GenericTextMatch patterns = 2 [(validate.rules).repeated = {min_items: 1}];
}
// Tap output configuration.
message OutputConfig {
option (udpa.annotations.versioning).previous_message_type =
"envoy.service.tap.v2alpha.OutputConfig";
// Output sinks for tap data. Currently a single sink is allowed in the list. Once multiple
// sink types are supported this constraint will be relaxed.
repeated OutputSink sinks = 1 [(validate.rules).repeated = {min_items: 1 max_items: 1}];
// For buffered tapping, the maximum amount of received body that will be buffered prior to
// truncation. If truncation occurs, the :ref:`truncated
// <envoy_v3_api_field_data.tap.v3.Body.truncated>` field will be set. If not specified, the
// default is 1KiB.
google.protobuf.UInt32Value max_buffered_rx_bytes = 2;
// For buffered tapping, the maximum amount of transmitted body that will be buffered prior to
// truncation. If truncation occurs, the :ref:`truncated
// <envoy_v3_api_field_data.tap.v3.Body.truncated>` field will be set. If not specified, the
// default is 1KiB.
google.protobuf.UInt32Value max_buffered_tx_bytes = 3;
// Indicates whether taps produce a single buffered message per tap, or multiple streamed
// messages per tap in the emitted :ref:`TraceWrapper
// <envoy_v3_api_msg_data.tap.v3.TraceWrapper>` messages. Note that streamed tapping does not
// mean that no buffering takes place. Buffering may be required if data is processed before a
// match can be determined. See the HTTP tap filter :ref:`streaming
// <config_http_filters_tap_streaming>` documentation for more information.
bool streaming = 4;
}
// Tap output sink configuration.
// [#next-free-field: 6]
message OutputSink {
option (udpa.annotations.versioning).previous_message_type =
"envoy.service.tap.v2alpha.OutputSink";
// Output format. All output is in the form of one or more :ref:`TraceWrapper
// <envoy_v3_api_msg_data.tap.v3.TraceWrapper>` messages. This enumeration indicates
// how those messages are written. Note that not all sinks support all output formats. See
// individual sink documentation for more information.
enum Format {
// Each message will be written as JSON. Any :ref:`body <envoy_v3_api_msg_data.tap.v3.Body>`
// data will be present in the :ref:`as_bytes
// <envoy_v3_api_field_data.tap.v3.Body.as_bytes>` field. This means that body data will be
// base64 encoded as per the `proto3 JSON mappings
// <https://developers.google.com/protocol-buffers/docs/proto3#json>`_.
JSON_BODY_AS_BYTES = 0;
// Each message will be written as JSON. Any :ref:`body <envoy_v3_api_msg_data.tap.v3.Body>`
// data will be present in the :ref:`as_string
// <envoy_v3_api_field_data.tap.v3.Body.as_string>` field. This means that body data will be
// string encoded as per the `proto3 JSON mappings
// <https://developers.google.com/protocol-buffers/docs/proto3#json>`_. This format type is
// useful when it is known that that body is human readable (e.g., JSON over HTTP) and the
// user wishes to view it directly without being forced to base64 decode the body.
JSON_BODY_AS_STRING = 1;
// Binary proto format. Note that binary proto is not self-delimiting. If a sink writes
// multiple binary messages without any length information the data stream will not be
// useful. However, for certain sinks that are self-delimiting (e.g., one message per file)
// this output format makes consumption simpler.
PROTO_BINARY = 2;
// Messages are written as a sequence tuples, where each tuple is the message length encoded
// as a `protobuf 32-bit varint
// <https://developers.google.com/protocol-buffers/docs/reference/cpp/google.protobuf.io.coded_stream>`_
// followed by the binary message. The messages can be read back using the language specific
// protobuf coded stream implementation to obtain the message length and the message.
PROTO_BINARY_LENGTH_DELIMITED = 3;
// Text proto format.
PROTO_TEXT = 4;
}
// Sink output format.
Format format = 1 [(validate.rules).enum = {defined_only: true}];
oneof output_sink_type {
option (validate.required) = true;
// Tap output will be streamed out the :http:post:`/tap` admin endpoint.
//
// .. attention::
//
// It is only allowed to specify the streaming admin output sink if the tap is being
// configured from the :http:post:`/tap` admin endpoint. Thus, if an extension has
// been configured to receive tap configuration from some other source (e.g., static
// file, XDS, etc.) configuring the streaming admin output type will fail.
StreamingAdminSink streaming_admin = 2;
// Tap output will be written to a file per tap sink.
FilePerTapSink file_per_tap = 3;
// [#not-implemented-hide:]
// GrpcService to stream data to. The format argument must be PROTO_BINARY.
// [#comment: TODO(samflattery): remove cleanup in uber_per_filter.cc once implemented]
StreamingGrpcSink streaming_grpc = 4;
// Tap output will be buffered in a single block before flushing to the :http:post:`/tap` admin endpoint
//
// .. attention::
//
// It is only allowed to specify the buffered admin output sink if the tap is being
// configured from the :http:post:`/tap` admin endpoint. Thus, if an extension has
// been configured to receive tap configuration from some other source (e.g., static
// file, XDS, etc.) configuring the buffered admin output type will fail.
BufferedAdminSink buffered_admin = 5;
}
}
// Streaming admin sink configuration.
message StreamingAdminSink {
option (udpa.annotations.versioning).previous_message_type =
"envoy.service.tap.v2alpha.StreamingAdminSink";
}
// BufferedAdminSink configures a tap output to collect traces without returning them until
// one of multiple criteria are satisfied.
// Similar to StreamingAdminSink, it is only allowed to specify the buffered admin output
// sink if the tap is being configured from the ``/tap`` admin endpoint.
message BufferedAdminSink {
// Stop collecting traces when the specified number are collected.
// If other criteria for ending collection are reached first, this value will not be used.
uint64 max_traces = 1 [(validate.rules).uint64 = {gt: 0}];
// Acts as a fallback to prevent the client from waiting for long periods of time.
// After timeout has occurred, a buffer flush will be triggered, returning the traces buffered so far.
// This may result in returning fewer traces than were requested, and in the case that no traces are
// buffered during this time, no traces will be returned.
// Specifying 0 for the timeout value (or not specifying a value at all) indicates an infinite timeout.
google.protobuf.Duration timeout = 2;
}
// The file per tap sink outputs a discrete file for every tapped stream.
message FilePerTapSink {
option (udpa.annotations.versioning).previous_message_type =
"envoy.service.tap.v2alpha.FilePerTapSink";
// Path prefix. The output file will be of the form <path_prefix>_<id>.pb, where <id> is an
// identifier distinguishing the recorded trace for stream instances (the Envoy
// connection ID, HTTP stream ID, etc.).
string path_prefix = 1 [(validate.rules).string = {min_len: 1}];
}
// [#not-implemented-hide:] Streaming gRPC sink configuration sends the taps to an external gRPC
// server.
message StreamingGrpcSink {
option (udpa.annotations.versioning).previous_message_type =
"envoy.service.tap.v2alpha.StreamingGrpcSink";
// Opaque identifier, that will be sent back to the streaming grpc server.
string tap_id = 1;
// The gRPC server that hosts the Tap Sink Service.
core.v3.GrpcService grpc_service = 2 [(validate.rules).message = {required: true}];
}