Traffic capture

Envoy currently provides an experimental transport socket extension that can intercept traffic and write to a protobuf capture file.

Warning

This feature is experimental and has a known limitation that it will OOM for large traces on a given socket. It can also be disabled in the build if there are security concerns, see https://github.com/envoyproxy/envoy/blob/master/bazel/README.md#disabling-extensions.

Configuration

Capture can be configured on Listener and Cluster transport sockets, providing the ability to interpose on downstream and upstream L4 connections respectively.

To configure traffic capture, add an envoy.transport_sockets.capture transport socket configuration to the listener or cluster. For a plain text socket this might look like:

  1. transport_socket:
  2.   name: envoy.transport_sockets.capture
  3.   config:
  4.     file_sink:
  5.       path_prefix: /some/capture/path
  6.     transport_socket:
  7.       name: raw_buffer

For a TLS socket, this will be:

  1. transport_socket:
  2.   name: envoy.transport_sockets.capture
  3.   config:
  4.     file_sink:
  5.       path_prefix: /some/capture/path
  6.     transport_socket:
  7.       name: ssl
  8.       config: <TLS context>

where the TLS context configuration replaces any existing downstream or upstream TLS configuration on the listener or cluster, respectively.

Each unique socket instance will generate a trace file prefixed with path_prefix. E.g. /some/capture/path_0.pb.

PCAP generation

The generated trace file can be converted to libpcap format, suitable for analysis with tools such as Wireshark with the capture2pcap utility, e.g.:

  1. bazel run @envoy_api//tools:capture2pcap /some/capture/path_0.pb path_0.pcap
  2. tshark -r path_0.pcap -d "tcp.port==10000,http2" -P
  3.   1   0.000000    127.0.0.1 → 127.0.0.1    HTTP2 157 Magic, SETTINGS, WINDOW_UPDATE, HEADERS
  4.   2   0.013713    127.0.0.1 → 127.0.0.1    HTTP2 91 SETTINGS, SETTINGS, WINDOW_UPDATE
  5.   3   0.013820    127.0.0.1 → 127.0.0.1    HTTP2 63 SETTINGS
  6.   4   0.128649    127.0.0.1 → 127.0.0.1    HTTP2 5586 HEADERS
  7.   5   0.130006    127.0.0.1 → 127.0.0.1    HTTP2 7573 DATA
  8.   6   0.131044    127.0.0.1 → 127.0.0.1    HTTP2 3152 DATA, DATA