1? my $ctx = $main::context;
2? $_mt->wrapper_file("wrapper.mt", "Configure", "Status Directives")->(sub {
3
4<p>
5The status handler exposes the current states of the HTTP server.
6This document describes the configuration directives of the handler.
7</p>
8
9? $ctx->{directive_list}->()->(sub {
10
11<?
12$ctx->{directive}->(
13    name    => "status",
14    levels  => [ qw(path) ],
15    since   => '2.0',
16    desc    => <<'EOT',
17If the argument is <code>ON</code>, the directive registers the status handler to the current path.
18EOT
19)->(sub {
20?>
21<p>
22Access to the handler should be <a href="configure/mruby.html#access-control">restricted</a>, considering the fact that the status includes the details of in-flight HTTP requests.
23The example below uses <a href="configure/basic_auth.html">Basic authentication</a>.
24</p>
25<?= $ctx->{example}->("Exposing status with Basic authentication", <<'EOT');
26paths:
27  /server-status:
28    mruby.handler: |
29      require "htpasswd.rb"
30      Htpasswd.new("/path/to/.htpasswd", "status")
31    status: ON
32EOT
33?>
34<p>
35The information returned by the <code>/json</code> handler can be filtered out using the optional <code>show=module1,module2</code> parameter.
36There are currently three modules defined:
37<ul>
38<li><code>requests</code>: displays the requests currently in-flight.</li>
39<li><code>durations</code>: displays durations statistics for requests since server start time in seconds (returns all zeros unless <code>duration-stats</code> is <code>ON</code>).</li>
40<li><code>errors</code>: displays counters for internally generated errors.</li>
41<li><code>main</code>: displays general daemon-wide stats.</li>
42</ul>
43</p>
44? })
45
46<?
47$ctx->{directive}->(
48    name    => "duration-stats",
49    levels  => [ qw(global) ],
50    since   => '2.1',
51    default => 'duration-stats: OFF',
52    desc    => q{Gather timing stats for requests.},
53)->(sub {
54?>
55</p>
56<p>
57If the argument is <code>ON</code>, this directive populates duration statistics in seconds, to be consumed by status handlers.
58Enabling this feature has a noticeable CPU and memory impact.
59</p>
60<p>
61Note that the time spent while processing a request in a blocking manner (such as opening a file or a mruby handler that does invoke a network operation) will not be reflected to the <code>process_time</code> element of the duration stats due to the fact that the timer being used for measuring the time spent is updated only once per loop.
62</p>
63? })
64
65? })
66
67? })
68