data-plane-api/envoy/service/tap/v2alpha/common.proto

syntax = "proto3";

import "envoy/api/v2/route/route.proto";

import "validate/validate.proto";

package envoy.service.tap.v2alpha;
option java_package = "io.envoyproxy.envoy.service.tap.v2alpha";

// [#protodoc-title: Common tap configuration]

// Tap configuration.
message TapConfig {
  // The match configuration. If the configuration matches the data source being tapped, a tap will
  // occur, with the result written to the configured output.
  MatchPredicate match_config = 1 [(validate.rules).message.required = true];

  // The tap output configuration. If a match configuration matches a data source being tapped,
  // a tap will occur and the data will be written to the configured output.
  OutputConfig output_config = 2 [(validate.rules).message.required = true];

  // [#comment:TODO(mattklein123): Rate limiting]
}

// Tap match configuration. This is a recursive structure which allows complex nested match
// configurations to be built using various logical operators.
message MatchPredicate {
  // A set of match configurations used for logical operations.
  message MatchSet {
    // The list of rules that make up the set.
    repeated MatchPredicate rules = 1 [(validate.rules).repeated .min_items = 2];
  }

  oneof rule {
    option (validate.required) = true;

    // A set that describes a logical OR. If any member of the set matches, the match configuration
    // matches.
    MatchSet or_match = 1;

    // A set that describes a logical AND. If all members of the set match, the match configuration
    // matches.
    MatchSet and_match = 2;

    // A negation match. The match configuration will match if the negated match condition matches.
    MatchPredicate not_match = 3;

    // The match configuration will always match.
    bool any_match = 4 [(validate.rules).bool.const = true];

    // HTTP request headers match configuration.
    HttpHeadersMatch http_request_headers_match = 5;

    // HTTP request trailers match configuration.
    HttpHeadersMatch http_request_trailers_match = 6;

    // HTTP response headers match configuration.
    HttpHeadersMatch http_response_headers_match = 7;

    // HTTP response trailers match configuration.
    HttpHeadersMatch http_response_trailers_match = 8;
  }
}

// HTTP headers match configuration.
message HttpHeadersMatch {
  // HTTP headers to match.
  repeated api.v2.route.HeaderMatcher headers = 1;
}

// Tap output configuration.
message OutputConfig {
  // Output sinks for tap data. Currently a single sink is allowed in the list. Once multiple
  // sink types are supported this constraint will be relaxed.
  repeated OutputSink sinks = 1 [(validate.rules).repeated = {min_items: 1, max_items: 1}];

  // [#comment:TODO(mattklein123): Output filtering. E.g., certain headers, truncated body, etc.]
}

// Tap output sink configuration.
message OutputSink {
  oneof output_sink_type {
    option (validate.required) = true;

    // Tap output will be streamed out the :http:post:`/tap` admin endpoint.
    //
    // .. attention::
    //
    //   It is only allowed to specify the streaming admin output sink if the tap is being
    //   configured from the :http:post:`/tap` admin endpoint. Thus, if an extension has
    //   been configured to receive tap configuration from some other source (e.g., static
    //   file, XDS, etc.) configuring the streaming admin output type will fail.
    StreamingAdminSink streaming_admin = 1;

    // Tap output will be written to a file per tap sink.
    FilePerTapSink file_per_tap = 2;
  }
}

// Streaming admin sink configuration.
message StreamingAdminSink {
}

// The file per tap sink outputs a discrete file for every tapped stream.
message FilePerTapSink {
  // Path prefix. The output file will be of the form <path_prefix>_<id>.pb, where <id> is an
  // identifier distinguishing the recorded trace for stream instances (the Envoy
  // connection ID, HTTP stream ID, etc.).
  string path_prefix = 1 [(validate.rules).string.min_bytes = 1];

  // File format.
  enum Format {
    // Binary proto format.
    PROTO_BINARY = 0;
    // Text proto format.
    PROTO_TEXT = 1;
  }
  Format format = 2 [(validate.rules).enum.defined_only = true];
}