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()
    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
    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

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