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