data-plane-api/envoy/config/accesslog/v3/accesslog.proto

syntax = "proto3";

package envoy.config.accesslog.v3;

import "envoy/config/core/v3/base.proto";
import "envoy/config/route/v3/route_components.proto";
import "envoy/type/matcher/v3/metadata.proto";
import "envoy/type/v3/percent.proto";

import "google/protobuf/any.proto";
import "google/protobuf/wrappers.proto";

import "udpa/annotations/status.proto";
import "udpa/annotations/versioning.proto";
import "validate/validate.proto";

option java_package = "io.envoyproxy.envoy.config.accesslog.v3";
option java_outer_classname = "AccesslogProto";
option java_multiple_files = true;
option go_package = "github.com/envoyproxy/go-control-plane/envoy/config/accesslog/v3;accesslogv3";
option (udpa.annotations.file_status).package_version_status = ACTIVE;

// [#protodoc-title: Common access log types]

message AccessLog {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.filter.accesslog.v2.AccessLog";

  reserved 3;

  reserved "config";

  // The name of the access log extension configuration.
  string name = 1;

  // Filter which is used to determine if the access log needs to be written.
  AccessLogFilter filter = 2;

  // Custom configuration that must be set according to the access logger extension being instantiated.
  // [#extension-category: envoy.access_loggers]
  oneof config_type {
    google.protobuf.Any typed_config = 4;
  }
}

// [#next-free-field: 13]
message AccessLogFilter {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.filter.accesslog.v2.AccessLogFilter";

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

    // Status code filter.
    StatusCodeFilter status_code_filter = 1;

    // Duration filter.
    DurationFilter duration_filter = 2;

    // Not health check filter.
    NotHealthCheckFilter not_health_check_filter = 3;

    // Traceable filter.
    TraceableFilter traceable_filter = 4;

    // Runtime filter.
    RuntimeFilter runtime_filter = 5;

    // And filter.
    AndFilter and_filter = 6;

    // Or filter.
    OrFilter or_filter = 7;

    // Header filter.
    HeaderFilter header_filter = 8;

    // Response flag filter.
    ResponseFlagFilter response_flag_filter = 9;

    // gRPC status filter.
    GrpcStatusFilter grpc_status_filter = 10;

    // Extension filter.
    // [#extension-category: envoy.access_loggers.extension_filters]
    ExtensionFilter extension_filter = 11;

    // Metadata Filter
    MetadataFilter metadata_filter = 12;
  }
}

// Filter on an integer comparison.
message ComparisonFilter {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.filter.accesslog.v2.ComparisonFilter";

  enum Op {
    // =
    EQ = 0;

    // >=
    GE = 1;

    // <=
    LE = 2;
  }

  // Comparison operator.
  Op op = 1 [(validate.rules).enum = {defined_only: true}];

  // Value to compare against.
  core.v3.RuntimeUInt32 value = 2 [(validate.rules).message = {required: true}];
}

// Filters on HTTP response/status code.
message StatusCodeFilter {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.filter.accesslog.v2.StatusCodeFilter";

  // Comparison.
  ComparisonFilter comparison = 1 [(validate.rules).message = {required: true}];
}

// Filters on total request duration in milliseconds.
message DurationFilter {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.filter.accesslog.v2.DurationFilter";

  // Comparison.
  ComparisonFilter comparison = 1 [(validate.rules).message = {required: true}];
}

// Filters for requests that are not health check requests. A health check
// request is marked by the health check filter.
message NotHealthCheckFilter {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.filter.accesslog.v2.NotHealthCheckFilter";
}

// Filters for requests that are traceable. See the tracing overview for more
// information on how a request becomes traceable.
message TraceableFilter {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.filter.accesslog.v2.TraceableFilter";
}

// Filters for random sampling of requests.
message RuntimeFilter {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.filter.accesslog.v2.RuntimeFilter";

  // Runtime key to get an optional overridden numerator for use in the
  // ``percent_sampled`` field. If found in runtime, this value will replace the
  // default numerator.
  string runtime_key = 1 [(validate.rules).string = {min_len: 1}];

  // The default sampling percentage. If not specified, defaults to 0% with
  // denominator of 100.
  type.v3.FractionalPercent percent_sampled = 2;

  // By default, sampling pivots on the header
  // :ref:`x-request-id<config_http_conn_man_headers_x-request-id>` being
  // present. If :ref:`x-request-id<config_http_conn_man_headers_x-request-id>`
  // is present, the filter will consistently sample across multiple hosts based
  // on the runtime key value and the value extracted from
  // :ref:`x-request-id<config_http_conn_man_headers_x-request-id>`. If it is
  // missing, or ``use_independent_randomness`` is set to true, the filter will
  // randomly sample based on the runtime key value alone.
  // ``use_independent_randomness`` can be used for logging kill switches within
  // complex nested :ref:`AndFilter
  // <envoy_v3_api_msg_config.accesslog.v3.AndFilter>` and :ref:`OrFilter
  // <envoy_v3_api_msg_config.accesslog.v3.OrFilter>` blocks that are easier to
  // reason about from a probability perspective (i.e., setting to true will
  // cause the filter to behave like an independent random variable when
  // composed within logical operator filters).
  bool use_independent_randomness = 3;
}

// Performs a logical “and” operation on the result of each filter in filters.
// Filters are evaluated sequentially and if one of them returns false, the
// filter returns false immediately.
message AndFilter {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.filter.accesslog.v2.AndFilter";

  repeated AccessLogFilter filters = 1 [(validate.rules).repeated = {min_items: 2}];
}

// Performs a logical “or” operation on the result of each individual filter.
// Filters are evaluated sequentially and if one of them returns true, the
// filter returns true immediately.
message OrFilter {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.filter.accesslog.v2.OrFilter";

  repeated AccessLogFilter filters = 2 [(validate.rules).repeated = {min_items: 2}];
}

// Filters requests based on the presence or value of a request header.
message HeaderFilter {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.filter.accesslog.v2.HeaderFilter";

  // Only requests with a header which matches the specified HeaderMatcher will
  // pass the filter check.
  route.v3.HeaderMatcher header = 1 [(validate.rules).message = {required: true}];
}

// Filters requests that received responses with an Envoy response flag set.
// A list of the response flags can be found
// in the access log formatter
// :ref:`documentation<config_access_log_format_response_flags>`.
message ResponseFlagFilter {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.filter.accesslog.v2.ResponseFlagFilter";

  // Only responses with the any of the flags listed in this field will be
  // logged. This field is optional. If it is not specified, then any response
  // flag will pass the filter check.
  repeated string flags = 1 [(validate.rules).repeated = {
    items {
      string {
        in: "LH"
        in: "UH"
        in: "UT"
        in: "LR"
        in: "UR"
        in: "UF"
        in: "UC"
        in: "UO"
        in: "NR"
        in: "DI"
        in: "FI"
        in: "RL"
        in: "UAEX"
        in: "RLSE"
        in: "DC"
        in: "URX"
        in: "SI"
        in: "IH"
        in: "DPE"
        in: "UMSDR"
        in: "RFCF"
        in: "NFCF"
        in: "DT"
        in: "UPE"
        in: "NC"
        in: "OM"
      }
    }
  }];
}

// Filters gRPC requests based on their response status. If a gRPC status is not
// provided, the filter will infer the status from the HTTP status code.
message GrpcStatusFilter {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.filter.accesslog.v2.GrpcStatusFilter";

  enum Status {
    OK = 0;
    CANCELED = 1;
    UNKNOWN = 2;
    INVALID_ARGUMENT = 3;
    DEADLINE_EXCEEDED = 4;
    NOT_FOUND = 5;
    ALREADY_EXISTS = 6;
    PERMISSION_DENIED = 7;
    RESOURCE_EXHAUSTED = 8;
    FAILED_PRECONDITION = 9;
    ABORTED = 10;
    OUT_OF_RANGE = 11;
    UNIMPLEMENTED = 12;
    INTERNAL = 13;
    UNAVAILABLE = 14;
    DATA_LOSS = 15;
    UNAUTHENTICATED = 16;
  }

  // Logs only responses that have any one of the gRPC statuses in this field.
  repeated Status statuses = 1 [(validate.rules).repeated = {items {enum {defined_only: true}}}];

  // If included and set to true, the filter will instead block all responses
  // with a gRPC status or inferred gRPC status enumerated in statuses, and
  // allow all other responses.
  bool exclude = 2;
}

// Filters based on matching dynamic metadata.
// If the matcher path and key correspond to an existing key in dynamic
// metadata, the request is logged only if the matcher value is equal to the
// metadata value. If the matcher path and key *do not* correspond to an
// existing key in dynamic metadata, the request is logged only if
// match_if_key_not_found is "true" or unset.
message MetadataFilter {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.filter.accesslog.v2.MetadataFilter";

  // Matcher to check metadata for specified value. For example, to match on the
  // access_log_hint metadata, set the filter to "envoy.common" and the path to
  // "access_log_hint", and the value to "true".
  type.matcher.v3.MetadataMatcher matcher = 1;

  // Default result if the key does not exist in dynamic metadata: if unset or
  // true, then log; if false, then don't log.
  google.protobuf.BoolValue match_if_key_not_found = 2;
}

// Extension filter is statically registered at runtime.
message ExtensionFilter {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.filter.accesslog.v2.ExtensionFilter";

  reserved 2;

  reserved "config";

  // The name of the filter implementation to instantiate. The name must
  // match a statically registered filter.
  string name = 1;

  // Custom configuration that depends on the filter being instantiated.
  oneof config_type {
    google.protobuf.Any typed_config = 3;
  }
}