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