aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2019-10-07 09:59:36 +0200
committerLoïc Hoguin <[email protected]>2019-10-07 09:59:36 +0200
commiteaed06370287c9708d2bf359dd1c2da1d392364c (patch)
treef113de6c8f00cfd685623761aa505309fa18c2d5 /doc/src/manual
parent3977f2b96fb8cc2164bfe28ee094b3e661a2fad9 (diff)
downloadcowboy-eaed06370287c9708d2bf359dd1c2da1d392364c.tar.gz
cowboy-eaed06370287c9708d2bf359dd1c2da1d392364c.tar.bz2
cowboy-eaed06370287c9708d2bf359dd1c2da1d392364c.zip
Document cowboy_metrics_h
Diffstat (limited to 'doc/src/manual')
-rw-r--r--doc/src/manual/cowboy_app.asciidoc1
-rw-r--r--doc/src/manual/cowboy_compress_h.asciidoc3
-rw-r--r--doc/src/manual/cowboy_metrics_h.asciidoc163
-rw-r--r--doc/src/manual/cowboy_stream_h.asciidoc3
4 files changed, 168 insertions, 2 deletions
diff --git a/doc/src/manual/cowboy_app.asciidoc b/doc/src/manual/cowboy_app.asciidoc
index d45c779..f51f3d2 100644
--- a/doc/src/manual/cowboy_app.asciidoc
+++ b/doc/src/manual/cowboy_app.asciidoc
@@ -36,6 +36,7 @@ Stream handlers:
* link:man:cowboy_stream_h(3)[cowboy_stream_h(3)] - Default stream handler
* link:man:cowboy_compress_h(3)[cowboy_compress_h(3)] - Compress stream handler
+* link:man:cowboy_metrics_h(3)[cowboy_metrics_h(3)] - Metrics stream handler
Behaviors:
diff --git a/doc/src/manual/cowboy_compress_h.asciidoc b/doc/src/manual/cowboy_compress_h.asciidoc
index ee39cae..6c171ed 100644
--- a/doc/src/manual/cowboy_compress_h.asciidoc
+++ b/doc/src/manual/cowboy_compress_h.asciidoc
@@ -28,7 +28,7 @@ opts() :: #{
}
----
-Configuration for the default stream handler.
+Configuration for the compress stream handler.
The default value is given next to the option name:
@@ -57,4 +57,5 @@ The compress stream handler does not produce any event.
link:man:cowboy(7)[cowboy(7)],
link:man:cowboy_stream(3)[cowboy_stream(3)],
+link:man:cowboy_metrics_h(3)[cowboy_metrics_h(3)],
link:man:cowboy_stream_h(3)[cowboy_stream_h(3)]
diff --git a/doc/src/manual/cowboy_metrics_h.asciidoc b/doc/src/manual/cowboy_metrics_h.asciidoc
new file mode 100644
index 0000000..a14b10b
--- /dev/null
+++ b/doc/src/manual/cowboy_metrics_h.asciidoc
@@ -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)]
diff --git a/doc/src/manual/cowboy_stream_h.asciidoc b/doc/src/manual/cowboy_stream_h.asciidoc
index caf113b..675c2e9 100644
--- a/doc/src/manual/cowboy_stream_h.asciidoc
+++ b/doc/src/manual/cowboy_stream_h.asciidoc
@@ -68,4 +68,5 @@ may not work properly if they are executed
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_compress_h(3)[cowboy_compress_h(3)],
+link:man:cowboy_metrics_h(3)[cowboy_metrics_h(3)]