.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "PROMSTATSD" "8" "Mar 18, 2024" "3.10.0" "Cyrus IMAP"
.SH NAME
promstatsd \- Cyrus IMAP documentation
.sp
Cyrus Prometheus statistics collating daemon
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\fBpromstatsd\fP [ \fB\-C\fP \fIconfig\-file\fP ] [ \fB\-v\fP ] [ \fB\-f\fP \fIfrequency\fP ] [ \fB\-d\fP ]

\fBpromstatsd\fP [ \fB\-C\fP \fIconfig\-file\fP ] [ \fB\-v\fP ] \fB\-c\fP

\fBpromstatsd\fP [ \fB\-C\fP \fIconfig\-file\fP ] [ \fB\-v\fP ] \fB\-1\fP
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
\fBpromstatsd\fP is the Cyrus Prometheus statistics collating daemon.
.sp
When the \fBprometheus_enabled\fP \fI\%imapd.conf(5)\fP setting is true,
various Cyrus service processes will count statistics as they run.
\fBpromstatsd\fP collates these statistics into a text\-based report that
Prometheus can ingest.
.sp
The report produced by \fBpromstatsd\fP is served by \fI\%httpd(8)\fP at
the \(dq/metrics\(dq URL, if \(dqprometheus\(dq has been set in \fBhttpmodules\fP in
\fI\%imapd.conf(5)\fP\&.
.sp
\fBpromstatsd\fP reads its configuration options out of the \fI\%imapd.conf(5)\fP file unless specified otherwise by \fB\-C\fP\&.
.sp
In the first synopsis, \fBpromstatsd\fP will run as a daemon, updating the
report at the specified \fIfrequency\fP\&.  If the optional \fB\-f\fP \fIfrequency\fP
argument is not provided, the \fBprometheus_update_freq\fP from
\fI\%imapd.conf(5)\fP will be used, which defaults to 10 seconds.  This
invocation should be run from the DAEMON section of \fI\%cyrus.conf(5)\fP
(see \fI\%Examples\fP below).
.sp
In the second synopsis, \fBpromstatsd\fP will clean up all statistics files and
exit.  The statistics Cyrus maintains are only valid while Cyrus is running,
so this invocation must be run from the START section of
\fI\%cyrus.conf(5)\fP (see \fI\%Examples\fP below) to clean up
after the previous run, before new service processes are started.
.sp
In the third synopsis, \fBpromstatsd\fP will immediately update the report
once, and then exit.  This can be safely used while another \fBpromstatsd\fP
process runs in daemon form.  It is useful if you need to update the report
\fInow\fP for some reason, rather than waiting for the daemon\(aqs next update.
.SH OPTIONS
.INDENT 0.0
.TP
.B \-C config\-file
Use the specified configuration file \fIconfig\-file\fP rather than the default \fI\%imapd.conf(5)\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-D
Run the external debugger specified in the \fBdebug_command\fP
\fI\%imapd.conf(5)\fP option.
.UNINDENT
.INDENT 0.0
.TP
.B \-1
Update the report once and exit.
.UNINDENT
.INDENT 0.0
.TP
.B \-c
Clean up the stats directory and exit.
.UNINDENT
.INDENT 0.0
.TP
.B \-d
Debug mode \-\- \fBpromstatsd\fP will not background itself, for aid in
debugging.
.UNINDENT
.INDENT 0.0
.TP
.B \-f frequency
Update the report every \fIfrequency\fP seconds.  If not specified, the
\fBprometheus_update_freq\fP from \fI\%imapd.conf(5)\fP will be used,
which defaults to 10 seconds.
.UNINDENT
.INDENT 0.0
.TP
.B \-v
Increase verbosity.  Can be specified multiple times.
.UNINDENT
.SH EXAMPLES
.sp
To regularly produce a report that Prometheus can consume, \fBpromstatsd\fP must
be run from the DAEMON section of \fI\%cyrus.conf(5)\fP as per the first
synopsis, like so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
DAEMON {
    \fBpromstatsd    cmd=\(dqpromstatsd\(dq\fP
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To ensure a clean statistical state at startup, \fBpromstatsd\fP must be run
from the START section of \fI\%cyrus.conf(5)\fP as per the second synopsis,
like so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
START {
    \fBstatscleanup  cmd=\(dqpromstatsd \-c\(dq\fP
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH HISTORY
.SH FILES
.SH SEE ALSO
.sp
\fI\%imapd.conf(5)\fP,
\fI\%cyrus.conf(5)\fP,
\fI\%httpd(8)\fP,
.SH AUTHOR
The Cyrus Team
.SH COPYRIGHT
1993–2024, The Cyrus Team
.\" Generated by docutils manpage writer.
.