package envoy.config.tap.v3

Get desktop application:
View/edit binary Protocol Buffers messages

BufferedAdminSink configures a tap output to collect traces without returning them until one of multiple criteria are satisfied. Similar to StreamingAdminSink, it is only allowed to specify the buffered admin output sink if the tap is being configured from the ``/tap`` admin endpoint.

Used in: OutputSink

• uint64 max_traces = 1

  Stop collecting traces when the specified number are collected. If other criteria for ending collection are reached first, this value will not be used.

• optional google.protobuf.Duration timeout = 2

  Acts as a fallback to prevent the client from waiting for long periods of time. After timeout has occurred, a buffer flush will be triggered, returning the traces buffered so far. This may result in returning fewer traces than were requested, and in the case that no traces are buffered during this time, no traces will be returned. Specifying 0 for the timeout value (or not specifying a value at all) indicates an infinite timeout.

The file per tap sink outputs a discrete file for every tapped stream.

Used in: OutputSink

• string path_prefix = 1

  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.).

HTTP generic body match configuration. List of text strings and hex strings to be located in HTTP body. All specified strings must be found in the HTTP body for positive match. The search may be limited to specified number of bytes from the body start. .. attention:: 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. If multiple patterns are specified, the process is repeated for each pattern. If location of a pattern is known, ``bytes_limit`` should be specified to scan only part of the http body.

Used in: MatchPredicate

• uint32 bytes_limit = 1

  Limits search to specified number of bytes - default zero (no limit - match entire captured buffer).

• repeated HttpGenericBodyMatch.GenericTextMatch patterns = 2

  List of patterns to match.

Used in: HttpGenericBodyMatch

• oneof rule

  • string string_match = 1

    Text string to be located in HTTP body.

  • bytes binary_match = 2

    Sequence of bytes to be located in HTTP body.

HTTP headers match configuration.

Used in: MatchPredicate

• repeated route.v3.HeaderMatcher headers = 1

  HTTP headers to match.

Tap match configuration. This is a recursive structure which allows complex nested match configurations to be built using various logical operators. [#next-free-field: 11]

Used in: MatchPredicate.MatchSet, TapConfig

• oneof rule

  • MatchPredicate.MatchSet or_match = 1

    A set that describes a logical OR. If any member of the set matches, the match configuration matches.

  • MatchPredicate.MatchSet and_match = 2

    A set that describes a logical AND. If all members of the set match, the match configuration matches.

  • MatchPredicate not_match = 3

    A negation match. The match configuration will match if the negated match condition matches.

  • bool any_match = 4

    The match configuration will always match.

  • HttpHeadersMatch http_request_headers_match = 5

    HTTP request headers match configuration.

  • HttpHeadersMatch http_request_trailers_match = 6

    HTTP request trailers match configuration.

  • HttpHeadersMatch http_response_headers_match = 7

    HTTP response headers match configuration.

  • HttpHeadersMatch http_response_trailers_match = 8

    HTTP response trailers match configuration.

  • HttpGenericBodyMatch http_request_generic_body_match = 9

    HTTP request generic body match configuration.

  • HttpGenericBodyMatch http_response_generic_body_match = 10

    HTTP response generic body match configuration.

A set of match configurations used for logical operations.

Used in: MatchPredicate

• repeated MatchPredicate rules = 1

  The list of rules that make up the set.

Tap output configuration.

Used in: TapConfig

• repeated OutputSink sinks = 1

  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.

• optional google.protobuf.UInt32Value max_buffered_rx_bytes = 2

  For buffered tapping, the maximum amount of received body that will be buffered prior to truncation. If truncation occurs, the :ref:`truncated <envoy_v3_api_field_data.tap.v3.Body.truncated>` field will be set. If not specified, the default is 1KiB.

• optional google.protobuf.UInt32Value max_buffered_tx_bytes = 3

  For buffered tapping, the maximum amount of transmitted body that will be buffered prior to truncation. If truncation occurs, the :ref:`truncated <envoy_v3_api_field_data.tap.v3.Body.truncated>` field will be set. If not specified, the default is 1KiB.

• bool streaming = 4

  Indicates whether taps produce a single buffered message per tap, or multiple streamed messages per tap in the emitted :ref:`TraceWrapper <envoy_v3_api_msg_data.tap.v3.TraceWrapper>` messages. Note that streamed tapping does not mean that no buffering takes place. Buffering may be required if data is processed before a match can be determined. See the HTTP tap filter :ref:`streaming <config_http_filters_tap_streaming>` documentation for more information.

Tap output sink configuration. [#next-free-field: 7]

Used in: OutputConfig

• OutputSink.Format format = 1

  Sink output format.

• oneof output_sink_type

  • StreamingAdminSink streaming_admin = 2

    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.

  • FilePerTapSink file_per_tap = 3

    Tap output will be written to a file per tap sink.

  • StreamingGrpcSink streaming_grpc = 4

    [#not-implemented-hide:] GrpcService to stream data to. The format argument must be PROTO_BINARY. [#comment: TODO(samflattery): remove cleanup in uber_per_filter.cc once implemented]

  • BufferedAdminSink buffered_admin = 5

    Tap output will be buffered in a single block before flushing to the :http:post:`/tap` admin endpoint .. attention:: It is only allowed to specify the buffered 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 buffered admin output type will fail.

  • core.v3.TypedExtensionConfig custom_sink = 6

    Tap output filter will be defined by an extension type

Output format. All output is in the form of one or more :ref:`TraceWrapper <envoy_v3_api_msg_data.tap.v3.TraceWrapper>` messages. This enumeration indicates how those messages are written. Note that not all sinks support all output formats. See individual sink documentation for more information.

Used in: OutputSink

• JSON_BODY_AS_BYTES = 0

  Each message will be written as JSON. Any :ref:`body <envoy_v3_api_msg_data.tap.v3.Body>` data will be present in the :ref:`as_bytes <envoy_v3_api_field_data.tap.v3.Body.as_bytes>` field. This means that body data will be base64 encoded as per the `proto3 JSON mappings <https://developers.google.com/protocol-buffers/docs/proto3#json>`_.

• JSON_BODY_AS_STRING = 1

  Each message will be written as JSON. Any :ref:`body <envoy_v3_api_msg_data.tap.v3.Body>` data will be present in the :ref:`as_string <envoy_v3_api_field_data.tap.v3.Body.as_string>` field. This means that body data will be string encoded as per the `proto3 JSON mappings <https://developers.google.com/protocol-buffers/docs/proto3#json>`_. This format type is useful when it is known that that body is human readable (e.g., JSON over HTTP) and the user wishes to view it directly without being forced to base64 decode the body.

• PROTO_BINARY = 2

  Binary proto format. Note that binary proto is not self-delimiting. If a sink writes multiple binary messages without any length information the data stream will not be useful. However, for certain sinks that are self-delimiting (e.g., one message per file) this output format makes consumption simpler.

• PROTO_BINARY_LENGTH_DELIMITED = 3

  Messages are written as a sequence tuples, where each tuple is the message length encoded as a `protobuf 32-bit varint <https://developers.google.com/protocol-buffers/docs/reference/cpp/google.protobuf.io.coded_stream>`_ followed by the binary message. The messages can be read back using the language specific protobuf coded stream implementation to obtain the message length and the message.

• PROTO_TEXT = 4

  Text proto format.

Streaming admin sink configuration.

Used in: OutputSink

(message has no fields)

[#not-implemented-hide:] Streaming gRPC sink configuration sends the taps to an external gRPC server.

Used in: OutputSink

• string tap_id = 1

  Opaque identifier, that will be sent back to the streaming grpc server.

• optional core.v3.GrpcService grpc_service = 2

  The gRPC server that hosts the Tap Sink Service.

Tap configuration.

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

Used in: admin.v3.TapRequest, extensions.common.tap.v3.CommonExtensionConfig

• optional MatchPredicate match_config = 1

  The match configuration. If the configuration matches the data source being tapped, a tap will occur, with the result written to the configured output. Exactly one of :ref:`match <envoy_v3_api_field_config.tap.v3.TapConfig.match>` and :ref:`match_config <envoy_v3_api_field_config.tap.v3.TapConfig.match_config>` must be set. If both are set, the :ref:`match <envoy_v3_api_field_config.tap.v3.TapConfig.match>` will be used.

• optional common.matcher.v3.MatchPredicate match = 4

  The match configuration. If the configuration matches the data source being tapped, a tap will occur, with the result written to the configured output. Exactly one of :ref:`match <envoy_v3_api_field_config.tap.v3.TapConfig.match>` and :ref:`match_config <envoy_v3_api_field_config.tap.v3.TapConfig.match_config>` must be set. If both are set, the :ref:`match <envoy_v3_api_field_config.tap.v3.TapConfig.match>` will be used.

• optional OutputConfig output_config = 2

  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.

• optional core.v3.RuntimeFractionalPercent tap_enabled = 3

  [#not-implemented-hide:] Specify if Tap matching is enabled. The % of requests\connections for which the tap matching is enabled. When not enabled, the request\connection will not be recorded. .. note:: This field defaults to 100/:ref:`HUNDRED <envoy_v3_api_enum_type.v3.FractionalPercent.DenominatorType>`.