= cowboy_metrics_h(3)

== Name

cowboy_metrics_h - Metrics stream handler

== Description

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

== Types

=== metrics()

[source,erlang]
----
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.

== Options

[source,erlang]
----
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()`.

metrics_req_filter::

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

metrics_resp_headers_filter::

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

== Events

The metrics stream handler does not produce any event.

== Changelog

* *2.7*: Module introduced.

== See also

link:man:cowboy(7)[cowboy(7)],
link:man:cowboy_stream(3)[cowboy_stream(3)],
link:man:cowboy_compress_h(3)[cowboy_compress_h(3)],
link:man:cowboy_stream_h(3)[cowboy_stream_h(3)],
link:man:cowboy_tracer_h(3)[cowboy_tracer_h(3)]
