h2

Type: Processing
Output: H2

The h2 task parses 2-way HTTP2 streams. It consumes data from the tlsplaintext or payload tasks.

Usage

It must run after tlsplaintext or payload tasks on the agent.

Configuration options

Many of the h2 options are controls over timeouts and the size of buffers. Knowing which options to change can be difficult. Here are a few options we think are good to start with.

To control how many flows can concurrently be tracked, the most important option is streamer_max_flows. If the number of flows exceeds this value, the oldest flow will be evicted from the cache and you are likely to see more missing headers.

The timeout of inactive flows is controlled by streamer_expire_flows. If you have flows that will be inactive for longer than this value, you will start seeing missing headers.

If responses are slow, you may want to increase round_tripper_max_age, so you give more time for requests and responses to be reassembled into full round trips.

Here is the full like of configuration options:

flower_max_flows

default 100000 The maximum number of flows tracked. When the limit is reached, the oldest flow is removed. The flower reassembles frames. This option limits the number of flows for which Frames can be reassembled concurrently. Uses LRU.

For example:

flower_max_flows:10000

flower_expire_flows

default 300s The time after which a flow is removed from the cache, if no new chunks for flow are seen.

For example:

flower_expire_flows:10s

flower_expire_interval

default 1s The interval at which the cache is checked for expired flows.

For example:

flower_expire_interval:10s

streamer_max_flows

default 100000 The maximum number of flows tracked. When the limit is reached, the oldest flow is removed. Streamer reassembles streams in each flow. This option limits the number of flows for which streams can be reassembled concurrently. Uses LRU.

For example:

streamer_max_flows:10000

streamer_max_streams_per_flow

default 1000 The maximum number of streams tracked per flow. When the limit is reached, the oldest stream is removed. Uses LRU.

For example:

streamer_max_streams_per_flow:10000

streamer_max_frames_buffer

default 1000 The maximum number of frames buffered per flow while attempting to maintain stream ordering. The order of the streams depends on the stream ID, and affects the dynamic header table, which required a complete order flow of streams in order to be valid.

For example:

streamer_max_frames_buffer:100

streamer_max_preflight_buffer

default 1000 The maximum number of frames buffered per new flow while attempting to discover the direction of the flow (which direction is client or server. Beyond this limit, if the direction could not be determined, the entire flow is dropped.

For example:

streamer_max_preflight_buffer:1000

streamer_expire_flows

default 300s The time after which a flow is removed from the cache, if no new frames for flow are seen.

For example:

streamer_expire_flows:10s

streamer_expire_streams

default 10s The time after which a stream is removed from the cache, if no new frames for stream are seen.

For example:

streamer_expire_streams:10s

streamer_expire_terminated_streams

default 2s The time after which a terminated stream is removed from the cache, if no new frames for stream are seen. Terminated streams are streams that have been closed by a RST_STREAM or a GO_AWAY. This timeout is usually shorter than streamer_expire_streams because terminated streams are not expected to receive any more frames. We do not expire them immediately on termination because we want to allow for a small window of time for any late frames to arrive.

For example:

streamer_expire_terminated_streams:10s

streamer_expire_interval

default 1s The interval at which the cache is checked for expired streams and flows.

For example:

streamer_expire_interval:10s

round_tripper_max_round_trips

default 100000 The maximum number of round trips tracked. When the limit is reached, the oldest round trip is removed. Uses LRU.

For example:

round_tripper_max_round_trips:1000

round_tripper_rst_stream_cache_size

default 1000 The maximum number of RST_STREAM frames tracked. When the limit is reached, the oldest RST_STREAM frame is removed. Uses LRU.

For example:

round_tripper_rst_stream_cache_size:100

round_tripper_go_away_cache_size

default 10000 The maximum number of GO_AWAY frames tracked. When the limit is reached, the oldest GO_AWAY frame is removed. Uses LRU.

For example:

round_tripper_go_away_cache_size:1000

round_tripper_max_age

default 20s The time after which a round trip is removed from the cache, if no new components for round trip are seen.

For example:

round_tripper_max_age:10s

round_tripper_max_age_terminated

default 5s The time after which a terminated round trip is removed from the cache, if no new components for round trip are seen. Terminate round trips are round trips that have been closed by a RST_STREAM or a GO_AWAY. This timeout is usually shorter than round_tripper_max_age because terminated round trips are not expected to receive any more components.

For example:

round_tripper_max_age_terminated:10s

round_tripper_check_age_interval

default 1s The interval at which the cache is checked for expired round trips.

For example:

round_tripper_check_age_interval:10s

round_tripper_disable_release_delay

default false Disable the full round trips release delay. Full round trips are round trips that received all their components. They are not released immediately, but after a delay, to allow for late RST_STREAM and GO_AWAY frames to be attached to the round trips. Set to true to disable this delay.

For example:

round_tripper_disable_release_delay:true

round_tripper_release_delay

default 2s The delay after which a full round trip is released. See round_tripper_disable_release_delay for more details.

For example:

round_tripper_release_delay:10s

reorder

default 0 By default, the h2 does not attempt to reorder incoming messages (default value of 0). The production of messages from the payload and tlsplaintext tasks can be out of order. This option will create a FIFO queue in front of the h2 reassembly. Messages will only be released from the FIFO queues as new messages arrive, so processing will be delayed by the time it takes to fill up the queue. For example, if the reorder queue is of 100 messages, and messages are produced at a rate of 10 messages per second, the output of h2 will be delayed by 10 seconds.

For example:

reorder:100

verbose

default false Verbose enables extra logging that will be output if the instance is set up with a debug or trace log level. This will produce substancially more logs (up to 2 logs per incoming message in trace) and is not recommended in production.

For example:

verbose:true

Conditions

h2 is not directly affected by conditions.

Output

h2.roundtrip: map Holds the reassembled HTTP2 round trip.
h2.roundtrip.flowID: string Unique identifier for the current bi-directional flow.
h2.roundtrip.streamID: string Unique identifier for the current single round trip.
h2.roundtrip.latency: uint Holds the duration in nanoseconds of the round trip, from the first 'packet' of the request, to the last 'packet' of the response. This is produced using the high precision in-kernel timer (see h2.roundtrip.(request|response).timing).
h2.roundtrip.timing: map - optional Holds the userspace absolute timing of the round trip. This corresponds to the timing as captured when 'packets' reach the h2 task.
h2.roundtrip.timing.from: uint The start time of the round trip capture, which is when we see the first 'packet' of the Request.
h2.roundtrip.timing.to: uint The end time of the round trip capture, which is when we see the lasr 'packet' of the Response.
h2.roundtrip.partial: boolean Partial false indicates the complete round trip was captured without errors. There could still be missing headers due to an incomplete dynamic header table. Partial true indicates the full round trip was no reassembled, and a partial round trip was published due to a timeout (no frames for the given round trip were produced for the duration defined by the timeout) or all components of a round trip (request and response headers and bodies) were encountered but one or more of them could not be parsed.
h2.roundtrip.request: map - optional Holds the HTTP2 Request.
h2.roundtrip.request.timing: map - optional Holds the kernelspace relative timing of the request in nanoseconds. This corresponds to the timing as captured in the kernel with high resolution and high precision, but it is a relative time (from system boot time but stops during suspend). This is useful for relative timing, to calculate precise duration of a round trip.
h2.roundtrip.request.timing.from: uint The start time of the round request, which is when we see the first 'packet' of the request.
h2.roundtrip.request.timing.to: uint The end time of the round request, which is when we see the last 'packet' of the request.
h2.roundtrip.request.header: map - optional Holds the HTTP2 Request Header.
h2.roundtrip.request.header.method: string The HTTP2 Method [pseudo header](https://httpwg.org/specs/rfc9113.html#HttpRequest) (such as "GET", "POST"…).
h2.roundtrip.request.header.path: string The HTTP2 Path pseudo header (e.g. "/path/here").
h2.roundtrip.request.header.authority: string The HTTP2 Authority pseudo header (a.k.a. the target host[:port]).
h2.roundtrip.request.header.scheme: string The HTTP2 Scheme pseudo header ("http" or "https").
h2.roundtrip.request.headers: map Holds the remaining non-pseudo headers.
h2.roundtrip.request.headers.fields: map - optional Holds the remaining headers name-value pairs, where the name is the normalized (lowercase) header key, and the value is an array of strings for the given key.
h2.roundtrip.request.headers.unknown: int - optional This is the number of headers that could not be parsed due to an incomplete dynamic header table.
h2.roundtrip.request.headers.valsMissingKey: string array - optional These are header values for which the header name is unknown due to an incomplete dynamic header table.
h2.roundtrip.request.headers.errors: string array - optional This will contain errors encountered while parsing the header.
h2.roundtrip.request.body: map - optional Holds the HTTP2 Request Body.
h2.roundtrip.request.body.multipart: boolean Is true if the body is a [multipart message](https://en.wikipedia.org/wiki/MIME#Multipart_messages).
h2.roundtrip.request.body.parts: map array This will contains the parts of the body payload. If the body is not a multipart message, there will only be 1 part.
h2.roundtrip.request.body.parts.contentType: string The mime type of the part/body.
h2.roundtrip.request.body.parts.guessed: bool Guessed indicates whether the Content-Type of the part was guessed. This can happen if the Content-Type header is missing due to an incomplete dynamic header table. Only non-multipart body can be guessed: by definition, if the body is recognized as multipart, the Content-Type was present. The guess can be wrong in the case the data can be parsed as JSON but is not actually JSON (e.g. a body of 3 is valid JSON).
h2.roundtrip.request.body.parts.jsonPayload: json - optional This will contain the parsed JSON part/body, if the part/body was recognized as JSON, either by the Content-Type field or through testing whether the data was valid JSON. The format of this field is unknown, it can be any valid JSON, including object, array, string, number, bool or null. This field is exclusive with the binPayload field, only one of them should be available.
h2.roundtrip.request.body.parts.binPayload: string - optional This will contain the Base 64 representation of the part/body. This field is exclusive with the jsonPayload field, only one of them should be available.
h2.roundtrip.response: map - optional Holds the HTTP2 Response.
h2.roundtrip.response.timing: map - optional Holds the kernelspace relative timing of the response in nanoseconds. This corresponds to the timing as captured in the kernel with high resolution and high precision, but it is a relative time (from system boot time but stops during suspend). This is useful for relative timing, to calculate precise duration of a response.
h2.roundtrip.response.timing.from: uint The start time of the response capture, which is when we see the first 'packet' of the response.
h2.roundtrip.response.timing.to: uint The end time of the response capture, which is when we see the last 'packet' of the response.
h2.roundtrip.response.header: map - optional Holds the HTTP2 Response Header.
h2.roundtrip.response.header.status: int The HTTP2 Status code [pseudo header](https://httpwg.org/specs/rfc9113.html#rfc.section.8.3.2) (such as 200, 404…).
h2.roundtrip.response.headers: map Holds the remaining non-pseudo headers.
h2.roundtrip.response.headers.fields: map - optional Holds the remaining headers name-value pairs, where the name is the normalized (no capitals) header key, and the value is an array of strings for the given key.
h2.roundtrip.response.headers.unknown: int - optional This is the number of headers that could not be parsed due to an incomplete dynamic header table.
h2.roundtrip.response.headers.valsMissingKey: string array - optional These are header values for which the header name is unknown due to an incomplete dynamic header table.
h2.roundtrip.response.headers.errors: string array - optional This will contain errors encountered while parsing the header.
h2.roundtrip.response.body: map - optional Holds the HTTP2 Response Body.
h2.roundtrip.response.body.multipart: boolean Is true if the body is a [multipart message](https://en.wikipedia.org/wiki/MIME#Multipart_messages).
h2.roundtrip.response.body.parts: map array This will contains the parts of the body payload. If the body is not a multipart message, there will only be 1 part.
h2.roundtrip.response.body.parts.contentType: string The mime type of the part/body.
h2.roundtrip.response.body.parts.guessed: bool Guessed indicates whether the Content-Type of the part was guessed. This can happen if the Content-Type header is missing due to an incomplete dynamic header table. Only non-multipart body can be guessed: by definition, if the body is recognized as multipart, the Content-Type was present. The guess can be wrong in the case the data can be parsed as JSON but is not actually JSON (e.g. a body of 3 is valid JSON).
h2.roundtrip.response.body.parts.jsonPayload: json - optional This will contain the parsed JSON part/body, if the part/body was recognized as JSON, either by the Content-Type field or through testing whether the data was valid JSON. The format of this field is unknown, it can be any valid JSON, including object, array, string, number, bool or null. This field is exclusive with the binPayload field, only one of them should be available.
h2.roundtrip.response.body.parts.binPayload: string - optional This will contain the Base 64 representation of the part/body. This field is exclusive with the jsonPayload field, only one of them should be available.
http2.net: map - optional Holds network connection information.
http2.net.af: map Linux Address family.
http2.net.proto: map L4 Protocol.
http2.net.srcAddr: map Source address.
http2.net.dstAddr: map Destination address.
http2.net.srcPort: map Source Port.
http2.net.dstPort: map Destination Port.
http2.process: map Holds the Process information.
http2.process.pid: uint32 Process PID.
http2.process.ppid: uint32 Process Parent PID.
http2.process.name: string Process name.
http2.process.cmd: string Command line string.
http2.process.exe: string Executable name.
http2.process.ns: string Namespace in the format of {device ID}-{inode number}.
http2.process.startedAt: string Time the process started.
http2.process.container: map Container information for process (if it is a container).
http2.process.container.ID: string ID of Container.
http2.process.container.Name: string Name of Container.