Document cowboy_tracer_h

7 files changed, 97 insertions, 3 deletions

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)]
diff --git a/src/cowboy_http.erl b/src/cowboy_http.erl
index 4a9808f..baedc1c 100644
--- a/src/cowboy_http.erl
+++ b/src/cowboy_http.erl
@@ -53,6 +53,7 @@
 	shutdown_timeout => timeout(),
 	stream_handlers => [module()],
 	tracer_callback => cowboy_tracer_h:tracer_callback(),
+	tracer_flags => [atom()],
 	tracer_match_specs => cowboy_tracer_h:tracer_match_specs(),
 	%% Open ended because configured stream handlers might add options.
 	_ => _
diff --git a/src/cowboy_http2.erl b/src/cowboy_http2.erl
index f85b78c..66f129e 100644
--- a/src/cowboy_http2.erl
+++ b/src/cowboy_http2.erl
@@ -64,6 +64,7 @@
 	stream_window_margin_size => 0..16#7fffffff,
 	stream_window_update_threshold => 0..16#7fffffff,
 	tracer_callback => cowboy_tracer_h:tracer_callback(),
+	tracer_flags => [atom()],
 	tracer_match_specs => cowboy_tracer_h:tracer_match_specs(),
 	%% Open ended because configured stream handlers might add options.
 	_ => _