package envoy.service.tap.v2alpha

Get desktop application:
View/edit binary Protocol Buffers messages

[#not-implemented-hide:] A tap service to receive incoming taps. Envoy will call StreamTaps to deliver captured taps to the server

• rpc StreamTaps (stream StreamTapsRequest, StreamTapsResponse)

  tap.proto:25

  Envoy will connect and send StreamTapsRequest messages forever. It does not expect any response to be sent as nothing would be done in the case of failure. The server should disconnect if it expects Envoy to reconnect.

  message StreamTapsRequest

  tap.proto:31

  [#not-implemented-hide:] Stream message for the Tap API. Envoy will open a stream to the server and stream taps without ever expecting a response.

  • optional StreamTapsRequest.Identifier identifier = 1

    Identifier data effectively is a structured metadata. As a performance optimization this will only be sent in the first message on the stream.

  • uint64 trace_id = 2

    The trace id. this can be used to merge together a streaming trace. Note that the trace_id is not guaranteed to be spatially or temporally unique.

  • optional data.tap.v2alpha.TraceWrapper trace = 3

    The trace data.

  message StreamTapsResponse

  tap.proto:54

  [#not-implemented-hide:]

  (message has no fields)

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 headers match configuration.

Used in: MatchPredicate

• repeated api.v2.route.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: 9]

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.

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_api_field_data.tap.v2alpha.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_api_field_data.tap.v2alpha.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_api_msg_data.tap.v2alpha.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.

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.

Output format. All output is in the form of one or more :ref:`TraceWrapper <envoy_api_msg_data.tap.v2alpha.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_api_msg_data.tap.v2alpha.Body>` data will be present in the :ref:`as_bytes <envoy_api_field_data.tap.v2alpha.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_api_msg_data.tap.v2alpha.Body>` data will be present in the :ref:`as_string <envoy_api_field_data.tap.v2alpha.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.

Used in: StreamTapsRequest

• optional api.v2.core.Node node = 1

  The node sending taps over the stream.

• string tap_id = 2

  The opaque identifier that was set in the :ref:`output config <envoy_api_field_service.tap.v2alpha.StreamingGrpcSink.tap_id>`.

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 api.v2.core.GrpcService grpc_service = 2

  The gRPC server that hosts the Tap Sink Service.

Tap configuration.

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

Used in: admin.v2alpha.TapRequest, config.common.tap.v2alpha.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.

• 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 api.v2.core.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_api_enum_type.FractionalPercent.DenominatorType>`.