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