1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
// file : monitor/monitor.cli
// license : MIT; see accompanying LICENSE file
include <vector>;
include <string>;
include <cstddef>; // size_t
include <cstdint>; // uint16_t
include <mod/module.cli>; // Reuse CLI support types.
"\section=1"
"\name=brep-monitor"
"\summary=monitor brep infrastructure"
namespace brep
{
namespace options
{
{
"<options> <brep-config> <toolchain> <name> <version>",
"\h|SYNOPSIS|
\c{\b{brep-monitor --help}\n
\b{brep-monitor --version}\n
\b{brep-monitor} [<options>] <brep-config> <toolchain> [<toolchain>...]}
\c{<toolchain> = <name>[\b{/}<version>]}
\h|DESCRIPTION|
\cb{brep-monitor} analyzes the \cb{brep} internal state and reports the
infrastructure issues printing their descriptions to \cb{stderr}.
The specified \cb{brep} module configuration file (<brep-config>) is
used to retrieve information required to access the databases and
deduce the expected behavior. Most of this information can be
overridden via the command line options.
Currently, only delayed package builds for the specified toolchains are
reported. If toolchain version is omitted then all package builds with
this toolchain name are considered.
\cb{brep-monitor} maintains its own state in the brep \cb{build}
database. In particular, it records timestamps of the reported package
build delays and optionally omits them from being reported again during
the timeout specified with the \cb{--report-timeout} option. If the
timeout is unspecified, then the report timestamps are not updated. To
report all delays and still update the timestamps specify the zero
report timeout.
By default, a brief report is printed. Use the \cb{--full-report}
option to obtain the full report (which may be large).
Note that \cb{brep-monitor} expects the \cb{build} database schema to
have already been created using \l{brep-migrate(1)}."
}
class monitor
{
"\h|OPTIONS|"
std::size_t --build-timeout
{
"<seconds>",
"Time to wait (in seconds) before considering a package build as
delayed. If unspecified, it is the sum of the package rebuild timeout
(normal rebuild timeout if the alternative timeout is unspecified and
the maximum of two otherwise) and the build result timeout (see the
\cb{build-normal-rebuild-timeout}, \cb{build-alt-rebuild-*}, and
\cb{build-result-timeout} \c{brep} module configuration options
for details).
Note that a package that was not built before it was archived is
always considered as delayed. However, to distinguish this case from
a situation where a package was archived before a configuration have
been added, \cb{brep-monitor} needs to observe the package as
buildable for this configuration before it is archived. As result, if
you run \cb{brep-monitor} periodically (for example, as a cron job),
then make sure its running period is less than the tenant archive
timeout."
}
std::size_t --report-timeout
{
"<seconds>",
"Time to wait (in seconds) before repeating a report of a package
build delay. By default there is no delay and all reports are
repeated."
}
bool --full-report
{
"Print the list of delayed package builds rather than just their number
per build configuration."
}
bool --clean
{
"Additionally clean the monitor state removing outdated information
related to non-existent packages, configurations, etc."
}
// Note that the web service would normally logs in under a different
// user (and potentially switch the role afterwords) and so falling back
// to brep's user name and password wouldn't make much sense.
//
std::string --build-db-user|-u
{
"<user>",
"\cb{build} database user name. If unspecified, then operating system
(login) name is used."
}
std::string --build-db-password
{
"<pass>",
"\cb{build} database password. If unspecified, then login without
password is expected to work."
}
std::string --build-db-name|-n = "brep_package"
{
"<name>",
"\cb{build} database name. If unspecified, then \cb{brep}'s
\cb{build-db-name} configuration option value is used."
}
std::string --build-db-host|-h
{
"<host>",
"\cb{build} database host name, address, or socket. If unspecified,
then \cb{brep}'s \cb{build-db-host} configuration option value is
used."
}
std::uint16_t --build-db-port|-p
{
"<port>",
"\cb{build} database port number. If unspecified, then \cb{brep}'s
\cb{build-db-port} configuration option value is used."
}
std::string --pager // String to allow empty value.
{
"<path>",
"The pager program to be used to show long text. Commonly used pager
programs are \cb{less} and \cb{more}. You can also specify additional
options that should be passed to the pager program with
\cb{--pager-option}. If an empty string is specified as the pager
program, then no pager will be used. If the pager program is not
explicitly specified, then \cb{brep-monitor} will try to use
\cb{less}. If it is not available, then no pager will be used."
}
std::vector<std::string> --pager-option
{
"<opt>",
"Additional option to be passed to the pager program. See \cb{--pager}
for more information on the pager program. Repeat this option to
specify multiple pager options."
}
bool --help {"Print usage information and exit."}
bool --version {"Print version and exit."}
};
"\h|EXIT STATUS|
\dl|
\li|\cb{0}
Success.|
\li|\cb{1}
Fatal error.|
\li|\cb{2}
An instance of \cb{brep-monitor} or some other \cb{brep} utility is
already running. Try again.|
\li|\cb{3}
Recoverable database error. Try again.||
"
}
}
|
