From 0342866c2e3490f2f9ef98ea9c8cefb405222818 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Mon, 7 Oct 2019 10:43:22 +0200
Subject: Document cowboy_tracer_h

---
 doc/src/manual/cowboy_app.asciidoc        |  1 +
 doc/src/manual/cowboy_compress_h.asciidoc |  3 +-
 doc/src/manual/cowboy_metrics_h.asciidoc  |  3 +-
 doc/src/manual/cowboy_stream_h.asciidoc   |  3 +-
 doc/src/manual/cowboy_tracer_h.asciidoc   | 88 +++++++++++++++++++++++++++++++
 5 files changed, 95 insertions(+), 3 deletions(-)
 create mode 100644 doc/src/manual/cowboy_tracer_h.asciidoc

(limited to 'doc/src/manual')

diff --git a/doc/src/manual/cowboy_app.asciidoc b/doc/src/manual/cowboy_app.asciidoc
index f51f3d2..8db84b1 100644
--- a/doc/src/manual/cowboy_app.asciidoc
+++ b/doc/src/manual/cowboy_app.asciidoc
@@ -37,6 +37,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
+* link:man:cowboy_tracer_h(3)[cowboy_tracer_h(3)] - Tracer stream handler
 
 Behaviors:
 
diff --git a/doc/src/manual/cowboy_compress_h.asciidoc b/doc/src/manual/cowboy_compress_h.asciidoc
index 6c171ed..c1d7b20 100644
--- a/doc/src/manual/cowboy_compress_h.asciidoc
+++ b/doc/src/manual/cowboy_compress_h.asciidoc
@@ -58,4 +58,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)]
+link:man:cowboy_stream_h(3)[cowboy_stream_h(3)],
+link:man:cowboy_tracer_h(3)[cowboy_tracer_h(3)]
diff --git a/doc/src/manual/cowboy_metrics_h.asciidoc b/doc/src/manual/cowboy_metrics_h.asciidoc
index a14b10b..c871d57 100644
--- a/doc/src/manual/cowboy_metrics_h.asciidoc
+++ b/doc/src/manual/cowboy_metrics_h.asciidoc
@@ -160,4 +160,5 @@ The metrics stream handler does not produce any event.
 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_stream_h(3)[cowboy_stream_h(3)],
+link:man:cowboy_tracer_h(3)[cowboy_tracer_h(3)]
diff --git a/doc/src/manual/cowboy_stream_h.asciidoc b/doc/src/manual/cowboy_stream_h.asciidoc
index 675c2e9..c25aa3d 100644
--- a/doc/src/manual/cowboy_stream_h.asciidoc
+++ b/doc/src/manual/cowboy_stream_h.asciidoc
@@ -69,4 +69,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_metrics_h(3)[cowboy_metrics_h(3)]
+link:man:cowboy_metrics_h(3)[cowboy_metrics_h(3)],
+link:man:cowboy_tracer_h(3)[cowboy_tracer_h(3)]
diff --git a/doc/src/manual/cowboy_tracer_h.asciidoc b/doc/src/manual/cowboy_tracer_h.asciidoc
new file mode 100644
index 0000000..e3592e4
--- /dev/null
+++ b/doc/src/manual/cowboy_tracer_h.asciidoc
@@ -0,0 +1,88 @@
+= cowboy_tracer_h(3)
+
+== Name
+
+cowboy_tracer_h - Tracer stream handler
+
+== Description
+
+The module `cowboy_tracer_h` can be used to conditionally
+trace streams based on information found in the request.
+Trace messages are given to the configured callback.
+
+== Options
+
+[source,erlang]
+----
+opts() :: #{
+    tracer_callback    => Callback,
+    tracer_flags       => [atom()],
+    tracer_match_specs => [MatchSpec]
+}
+
+Callback :: fun((init | terminate | tuple(), State) -> State)
+
+MatchSpec :: MatchPredicate
+           | {method, binary()}
+           | {host, binary()}
+           | {path, binary()}
+           | {path_start, binary()}
+           | {header, binary()}
+           | {header, binary(), binary()}
+           | {peer_ip, inet:ip_address()}
+
+MatchPredicate :: fun((cowboy_stream:streamid(),
+                       cowboy_req:req(),
+                       cowboy:opts()) -> boolean())
+}
+----
+
+Configuration for the tracer stream handler.
+
+This module will not set trace patterns. Those must be
+set by the user directly, either from the callback's
+`init` or, preferably, in advance.
+
+tracer_callback::
+
+The function that will be called for each trace
+events. It will also be called before any trace
+event with an argument `init`, and when the
+stream is terminated with an argument `terminate`.
++
+This option is required for tracing to be enabled.
+The tracer stream handler does nothing otherwise.
+
+tracer_flags::
+
+Trace flags to enable. See the documentation
+of `erlang:trace/3` for details. Note that all
+trace flags are allowed except for the `tracer`
+flag.
+
+tracer_match_specs::
+
+A list of match conditions that must all be
+fulfilled for the stream to be traced. Cowboy
+will compare these with the information found
+in the request and only enable tracing if all
+matches succeed.
++
+This option is required for tracing to be enabled.
+The tracer stream handler does nothing otherwise.
+
+== Events
+
+The tracer 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_metrics_h(3)[cowboy_metrics_h(3)],
+link:man:cowboy_stream_h(3)[cowboy_stream_h(3)]
-- 
cgit v1.2.3