...

Text file src/github.com/emissary-ingress/emissary/v3/api/envoy/service/tap/v2alpha/common.proto

Documentation: github.com/emissary-ingress/emissary/v3/api/envoy/service/tap/v2alpha

     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