aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-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.asciidoc3
-rw-r--r--doc/src/manual/cowboy_stream_h.asciidoc3
-rw-r--r--doc/src/manual/cowboy_tracer_h.asciidoc88
5 files changed, 95 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)]