Common tap configuration¶

This documentation is for the Envoy v3 API.

As of Envoy v1.18 the v2 API has been removed and is no longer supported.

If you are upgrading from v2 API config you may wish to view the v2 API documentation:

service/tap/v2alpha/common.proto

config.tap.v3.TapConfig¶

Tap configuration.

{
  "match_config": "{...}",
  "match": "{...}",
  "output_config": "{...}"
}

match_config: (config.tap.v3.MatchPredicate) 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 match and match_config must be set. If both are set, the match will be used.

match: (config.common.matcher.v3.MatchPredicate) 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 match and match_config must be set. If both are set, the match will be used.

output_config: (config.tap.v3.OutputConfig, REQUIRED) 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.

config.tap.v3.MatchPredicate¶

[config.tap.v3.MatchPredicate proto]

Tap match configuration. This is a recursive structure which allows complex nested match configurations to be built using various logical operators.

{
  "or_match": "{...}",
  "and_match": "{...}",
  "not_match": "{...}",
  "any_match": "...",
  "http_request_headers_match": "{...}",
  "http_request_trailers_match": "{...}",
  "http_response_headers_match": "{...}",
  "http_response_trailers_match": "{...}",
  "http_request_generic_body_match": "{...}",
  "http_response_generic_body_match": "{...}"
}

or_match

(config.tap.v3.MatchPredicate.MatchSet) A set that describes a logical OR. If any member of the set matches, the match configuration matches.

Precisely one of or_match, and_match, not_match, any_match, http_request_headers_match, http_request_trailers_match, http_response_headers_match, http_response_trailers_match, http_request_generic_body_match, http_response_generic_body_match must be set.

and_match

(config.tap.v3.MatchPredicate.MatchSet) A set that describes a logical AND. If all members of the set match, the match configuration matches.

Precisely one of or_match, and_match, not_match, any_match, http_request_headers_match, http_request_trailers_match, http_response_headers_match, http_response_trailers_match, http_request_generic_body_match, http_response_generic_body_match must be set.

not_match

(config.tap.v3.MatchPredicate) A negation match. The match configuration will match if the negated match condition matches.

Precisely one of or_match, and_match, not_match, any_match, http_request_headers_match, http_request_trailers_match, http_response_headers_match, http_response_trailers_match, http_request_generic_body_match, http_response_generic_body_match must be set.

any_match

(bool) The match configuration will always match.

Precisely one of or_match, and_match, not_match, any_match, http_request_headers_match, http_request_trailers_match, http_response_headers_match, http_response_trailers_match, http_request_generic_body_match, http_response_generic_body_match must be set.

http_request_headers_match

(config.tap.v3.HttpHeadersMatch) HTTP request headers match configuration.

Precisely one of or_match, and_match, not_match, any_match, http_request_headers_match, http_request_trailers_match, http_response_headers_match, http_response_trailers_match, http_request_generic_body_match, http_response_generic_body_match must be set.

http_request_trailers_match

(config.tap.v3.HttpHeadersMatch) HTTP request trailers match configuration.

Precisely one of or_match, and_match, not_match, any_match, http_request_headers_match, http_request_trailers_match, http_response_headers_match, http_response_trailers_match, http_request_generic_body_match, http_response_generic_body_match must be set.

http_response_headers_match

(config.tap.v3.HttpHeadersMatch) HTTP response headers match configuration.

Precisely one of or_match, and_match, not_match, any_match, http_request_headers_match, http_request_trailers_match, http_response_headers_match, http_response_trailers_match, http_request_generic_body_match, http_response_generic_body_match must be set.

http_response_trailers_match

(config.tap.v3.HttpHeadersMatch) HTTP response trailers match configuration.

Precisely one of or_match, and_match, not_match, any_match, http_request_headers_match, http_request_trailers_match, http_response_headers_match, http_response_trailers_match, http_request_generic_body_match, http_response_generic_body_match must be set.

http_request_generic_body_match

(config.tap.v3.HttpGenericBodyMatch) HTTP request generic body match configuration.

Precisely one of or_match, and_match, not_match, any_match, http_request_headers_match, http_request_trailers_match, http_response_headers_match, http_response_trailers_match, http_request_generic_body_match, http_response_generic_body_match must be set.

http_response_generic_body_match

(config.tap.v3.HttpGenericBodyMatch) HTTP response generic body match configuration.

Precisely one of or_match, and_match, not_match, any_match, http_request_headers_match, http_request_trailers_match, http_response_headers_match, http_response_trailers_match, http_request_generic_body_match, http_response_generic_body_match must be set.

config.tap.v3.MatchPredicate.MatchSet¶

[config.tap.v3.MatchPredicate.MatchSet proto]

A set of match configurations used for logical operations.

{
  "rules": []
}

rules: (repeated config.tap.v3.MatchPredicate, REQUIRED) The list of rules that make up the set.

config.tap.v3.HttpHeadersMatch¶

[config.tap.v3.HttpHeadersMatch proto]

HTTP headers match configuration.

{
  "headers": []
}

headers: (repeated config.route.v3.HeaderMatcher) HTTP headers to match.

config.tap.v3.HttpGenericBodyMatch¶

[config.tap.v3.HttpGenericBodyMatch proto]

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.

{
  "bytes_limit": "...",
  "patterns": []
}

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

patterns: (repeated config.tap.v3.HttpGenericBodyMatch.GenericTextMatch, REQUIRED) List of patterns to match.

config.tap.v3.HttpGenericBodyMatch.GenericTextMatch¶

[config.tap.v3.HttpGenericBodyMatch.GenericTextMatch proto]

{
  "string_match": "...",
  "binary_match": "..."
}

string_match

(string) Text string to be located in HTTP body.

Precisely one of string_match, binary_match must be set.

binary_match

(bytes) Sequence of bytes to be located in HTTP body.

Precisely one of string_match, binary_match must be set.

config.tap.v3.OutputConfig¶

[config.tap.v3.OutputConfig proto]

Tap output configuration.

{
  "sinks": [],
  "max_buffered_rx_bytes": "{...}",
  "max_buffered_tx_bytes": "{...}",
  "streaming": "..."
}

sinks: (repeated config.tap.v3.OutputSink, REQUIRED) 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.

max_buffered_rx_bytes: (UInt32Value) For buffered tapping, the maximum amount of received body that will be buffered prior to truncation. If truncation occurs, the truncated field will be set. If not specified, the default is 1KiB.

max_buffered_tx_bytes: (UInt32Value) For buffered tapping, the maximum amount of transmitted body that will be buffered prior to truncation. If truncation occurs, the truncated field will be set. If not specified, the default is 1KiB.

streaming: (bool) Indicates whether taps produce a single buffered message per tap, or multiple streamed messages per tap in the emitted 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 streaming documentation for more information.

config.tap.v3.OutputSink¶

[config.tap.v3.OutputSink proto]

Tap output sink configuration.

{
  "format": "...",
  "streaming_admin": "{...}",
  "file_per_tap": "{...}",
  "buffered_admin": "{...}"
}

format: (config.tap.v3.OutputSink.Format) Sink output format.

streaming_admin

(config.tap.v3.StreamingAdminSink) Tap output will be streamed out the POST /tap admin endpoint.

Attention

It is only allowed to specify the streaming admin output sink if the tap is being configured from the 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.

Precisely one of streaming_admin, file_per_tap, buffered_admin must be set.

file_per_tap

(config.tap.v3.FilePerTapSink) Tap output will be written to a file per tap sink.

Precisely one of streaming_admin, file_per_tap, buffered_admin must be set.

buffered_admin

(config.tap.v3.BufferedAdminSink) Tap output will be buffered in a single block before flushing to the POST /tap admin endpoint

Attention

It is only allowed to specify the buffered admin output sink if the tap is being configured from the 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.

Precisely one of streaming_admin, file_per_tap, buffered_admin must be set.

Enum config.tap.v3.OutputSink.Format¶

[config.tap.v3.OutputSink.Format proto]

Output format. All output is in the form of one or more 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.

JSON_BODY_AS_BYTES: (DEFAULT) ⁣Each message will be written as JSON. Any body data will be present in the as_bytes field. This means that body data will be base64 encoded as per the proto3 JSON mappings.

JSON_BODY_AS_STRING: ⁣Each message will be written as JSON. Any body data will be present in the as_string field. This means that body data will be string encoded as per the proto3 JSON mappings. 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: ⁣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: ⁣Messages are written as a sequence tuples, where each tuple is the message length encoded as a protobuf 32-bit varint 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: ⁣Text proto format.

config.tap.v3.StreamingAdminSink¶

[config.tap.v3.StreamingAdminSink proto]

Streaming admin sink configuration.

config.tap.v3.BufferedAdminSink¶

[config.tap.v3.BufferedAdminSink proto]

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.

{
  "max_traces": "...",
  "timeout": "{...}"
}

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

timeout: (Duration) 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.

config.tap.v3.FilePerTapSink¶

[config.tap.v3.FilePerTapSink proto]

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

{
  "path_prefix": "..."
}

path_prefix: (string, REQUIRED) 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.).