Debian Codegraph @

doc/html/_sources/imap/reference/manpages/systemcommands/promstatsd.rst.txt

raw
1 .. cyrusman:: promstatsd(8)
2
3 .. _imap-reference-manpages-systemcommands-promstatsd:
4
5 ==============
6 **promstatsd**
7 ==============
8
9 Cyrus Prometheus statistics collating daemon
10
11 Synopsis
12 ========
13
14 .. parsed-literal::
15
16 **promstatsd** [ **-C** *config-file* ] [ **-v** ] [ **-f** *service-frequency* ] [ **-d** ]
17
18 **promstatsd** [ **-C** *config-file* ] [ **-v** ] **-c**
19
20 **promstatsd** [ **-C** *config-file* ] [ **-v** ] **-1**
21
22 Description
23 ===========
24
25 **promstatsd** is the Cyrus Prometheus statistics collating daemon.
26
27 When the **prometheus_enabled** :cyrusman:`imapd.conf(5)` setting is true,
28 various Cyrus service processes will count statistics as they run.
29 **promstatsd** collates these statistics into a text-based report that
30 Prometheus can ingest.
31
32 The report produced by **promstatsd** is served by :cyrusman:`httpd(8)` at
33 the "/metrics" URL, if "prometheus" has been set in **httpmodules** in
34 :cyrusman:`imapd.conf(5)`.
35
36 **promstatsd** |default-conf-text|
37
38 In the first synopsis, **promstatsd** will run as a daemon, updating the
39 service and (optionally) usage reports at the frequencies set by the
40 **prometheus_service_update_freq** and **prometheus_usage_update_freq**
41 :cyrusman:`imapd.conf(5)` options, which default to 10s and disabled,
42 respectively. The optional **-f** *service-frequency* argument can be used to
43 override **prometheus_service_update_freq**. This invocation should be run
44 from the DAEMON section of :cyrusman:`cyrus.conf(5)` (see
45 :ref:`promstatsd-examples` below).
46
47 In the second synopsis, **promstatsd** will clean up all statistics files and
48 exit. The statistics Cyrus maintains are only valid while Cyrus is running,
49 so this invocation must be run from the START section of
50 :cyrusman:`cyrus.conf(5)` (see :ref:`promstatsd-examples` below) to clean up
51 after the previous run, before new service processes are started.
52
53 In the third synopsis, **promstatsd** will immediately update the report(s)
54 once, and then exit. This can be safely used while another **promstatsd**
55 process runs in daemon form. It is useful if you need to update the report
56 *now* for some reason, rather than waiting for the daemon's next update.
57
58 Options
59 =======
60
61 .. program:: promstatsd
62
63 .. option:: -C config-file
64
65 |cli-dash-c-text|
66
67 .. option:: -D
68
69 Run the external debugger specified in the **debug_command**
70 :cyrusman:`imapd.conf(5)` option.
71
72 .. option:: -1
73
74 Update the report(s) once and exit.
75
76 .. option:: -c
77
78 Clean up the stats directory and exit.
79
80 .. option:: -d
81
82 Debug mode -- **promstatsd** will not background itself, for aid in
83 debugging.
84
85 .. option:: -f service-frequency
86
87 Update the service report every *service-frequency* seconds. If not
88 specified, the **prometheus_service_update_freq** from
89 :cyrusman:`imapd.conf(5)` will be used, which defaults to 10 seconds.
90
91 .. option:: -v
92
93 Increase verbosity. Can be specified multiple times.
94
95 .. _promstatsd-examples:
96
97 Examples
98 ========
99
100 To regularly produce a report that Prometheus can consume, **promstatsd** must
101 be run from the DAEMON section of :cyrusman:`cyrus.conf(5)` as per the first
102 synopsis, like so:
103
104 .. parsed-literal::
105 DAEMON {
106 **promstatsd cmd="promstatsd"**
107 }
108
109 To ensure a clean statistical state at startup, **promstatsd** must be run
110 from the START section of :cyrusman:`cyrus.conf(5)` as per the second synopsis,
111 like so:
112
113 .. parsed-literal::
114 START {
115 **statscleanup cmd="promstatsd -c"**
116 }
117
118 History
119 =======
120
121 Files
122 =====
123
124 See Also
125 ========
126
127 :cyrusman:`imapd.conf(5)`,
128 :cyrusman:`cyrus.conf(5)`,
129 :cyrusman:`httpd(8)`,