...

Text file src/github.com/datawire/ambassador/v2/api/envoy/config/tap/v4alpha/common.proto

Documentation: github.com/datawire/ambassador/v2/api/envoy/config/tap/v4alpha

     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