|
|
@@ -0,0 +1,163 @@
|
|
|
+= 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)]
|
Loïc Hoguin