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