= 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)]