cowboy_metrics_h - Metrics stream handler


The module cowboy_metrics_h gathers metrics and other information about a stream. It then calls the configured callback with this data.



metrics() :: #{
    %% The identifier for this listener.
    ref := ranch:ref(),

    %% The pid for this connection.
    pid := pid(),

    %% The streamid also indicates the total number of requests on
    %% this connection (StreamID div 2 + 1).
    streamid := cowboy_stream:streamid(),

    %% The terminate reason is always useful.
    reason := cowboy_stream:reason(),

    %% A filtered Req object or a partial Req object
    %% depending on how far the request got to.
    req => cowboy_req:req(),
    partial_req => cowboy_stream:partial_req(),

    %% Response status.
    resp_status := cowboy:http_status(),

    %% Filtered response headers.
    resp_headers := cowboy:http_headers(),

    %% Start/end of the processing of the request.
    %% This represents the time from this stream handler's init
    %% to terminate.
    req_start => integer(),
    req_end => integer(),

    %% Start/end of the receiving of the request body.
    %% Begins when the first packet has been received.
    req_body_start => integer(),
    req_body_end => integer(),

    %% Start/end of the sending of the response.
    %% Begins when we send the headers and ends on the final
    %% packet of the response body. If everything is sent at
    %% once these values are identical.
    resp_start => integer(),
    resp_end => integer(),

    %% For early errors all we get is the time we received it.
    early_error_time => integer(),

    %% Start/end of spawned processes. This is where most of
    %% the user code lies, excluding stream handlers. On a
    %% default Cowboy configuration there should be only one
    %% process: the request process.
    procs => ProcMetrics,

    %% Informational responses sent before the final response.
    informational => [InformationalMetrics],

    %% Length of the request and response bodies. This does
    %% not include the framing.
    req_body_length => non_neg_integer(),
    resp_body_length => non_neg_integer(),

    %% Additional metadata set by the user.
    user_data => map()

InformationalMetrics :: #{
    %% Informational response status.
    status := cowboy:http_status(),

    %% Headers sent with the informational response.
    headers := cowboy:http_headers(),

    %% Time when the informational response was sent.
    time := integer()

ProcMetrics :: #{pid() => #{
    %% Time at which the process spawned.
    spawn := integer(),

    %% Time at which the process exited.
    exit => integer(),

    %% Reason for the process exit.
    reason => any()

Metrics given to the callback function.

Depending on the life of the stream the metrics may include more or less information.

The set_options command can be used to add additional metadata in the user_data metric. This can be used for example to add the handler module which was selected by the router. The option to be set is metrics_user_data. It takes a map which will be merged in the existing user_data map.


opts() :: #{
    metrics_callback => fun((metrics()) -> any()),
    metrics_req_filter => fun((cowboy_req:req()) -> map()),
    metrics_resp_headers_filter => fun((cowboy:http_headers()) -> cowboy:http_headers())

Configuration for the metrics stream handler.

metrics_callback - mandatory

The function that will be called upon completion of the stream. It only takes a single argument, the metrics().


A function applied to the Req to compact it and only keep required information. By default no filtering is done.


A function applied to the response headers to filter them and only keep required information. By default no filtering is done.


The metrics stream handler does not produce any event.


  • 2.7: Module introduced.

See also

cowboy(7), cowboy_stream(3), cowboy_compress_h(3), cowboy_stream_h(3), cowboy_tracer_h(3)

Cowboy 2.7 Function Reference


Version select

Like my work? Donate!

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and is fantastic:

Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.