1amtool(1) 0.23.0 amtool(1)
2
6 amtool - Tooling for the Prometheus alert manager
7
9 amtool [<flags>] <command> [<args> ...]
10
13 View and modify the current Alertmanager state.
14 Config File: The alertmanager tool will read a config file in YAML for‐
16 mat from one of two default config locations: $HOME/.con‐
17 fig/prometheus/amtool.yml or /etc/prometheus/amtool.yml
18 All flags can be given in the config file, but the following are the
20 suited for static configuration:
21 alertmanager.url Set a default alertmanager url for each
23 request
24 author Set a default author value for new silences. If
26 this argument is not specified then the username will be used
27 require-comment Bool, whether to require a comment on
29 silence creation. Defaults to true
30 output Set a default output type. Options are (simple,
32 extended, json)
33 date.format Sets the output format for dates. Defaults
35 to "2006-01-02 15:04:05 MST"
36 tls.insecure.skip.verify Skips TLS certificate verifica‐
38 tion for all HTTPS requests. Defaults to false.
39
42 -h, --help
43 Show context-sensitive help (also try --help-long and --help-
44 man).
45 --date.format="2006-01-02 15:04:05 MST"
47 Format of date output
48 -v, --verbose
50 Verbose running information
51 --alertmanager.url=http://localhost:9093/
53 Alertmanager to talk to
54 -o, --output=simple
56 Output formatter (simple, extended, json)
57 --timeout=30s
59 Timeout for the executed command
60 --tls.insecure.skip.verify
62 Skip TLS certificate verification
63 --version-check
65 Check alertmanager version. Use --no-version-check to disable.
66 --version
68 Show application version.
69
71 help [<command>...]
72 Show help.
73 alert query [<flags>] [<matcher-groups>...]
75 View and search through current alerts.
76 Amtool has a simplified prometheus query syntax, but contains robust
78 support for bash variable expansions. The non-option section of argu‐
79 ments constructs a list of "Matcher Groups" that will be used to filter
80 your query. The following examples will attempt to show this behaviour
81 in action:
82 amtool alert query alertname=foo node=bar
84 This query will match all alerts with the alertname=foo and
86 node=bar label value pairs set.
87 amtool alert query foo node=bar
89 If alertname is omitted and the first argument does not contain a
91 '=' or a '=~' then it will be assumed to be the value of the
92 alertname pair.
93 amtool alert query 'alertname=~foo.*'
95 As well as direct equality, regex matching is also supported. The
97 '=~' syntax (similar to prometheus) is used to represent a regex
98 match. Regex matching can be used in combination with a direct
99 match.
100 Amtool supports several flags for filtering the returned alerts by
102 state (inhibited, silenced, active, unprocessed). If none of these
103 flags is given, only active alerts are returned.
104 -i, --inhibited
107 Show inhibited alerts
108 -s, --silenced
110 Show silenced alerts
111 -a, --active
113 Show active alerts
114 -u, --unprocessed
116 Show unprocessed alerts
117 -r, --receiver=RECEIVER
119 Show alerts matching receiver (Supports regex syntax)
120 alert add [<flags>] [<labels>...]
122 Add a new alert.
123 This command is used to add a new alert to Alertmanager.
125 To add a new alert with labels:
127 amtool alert add alertname=foo node=bar
129 If alertname is omitted and the first argument does not contain a '='
131 then it will be assumed to be the value of the alertname pair.
132 amtool alert add foo node=bar
134 One or more annotations can be added using the --annotation flag:
136 amtool alert add foo node=bar --annotation=run‐
138 book='http://runbook.biz' --annotation=summary='summary of the
139 alert' --annotation=description='description of the alert'
140 Additional flags such as --generator-url, --start, and --end are also
142 supported.
143 --generator-url=GENERATOR-URL
146 Set the URL of the source that generated the alert
147 --start=START
149 Set when the alert should start. RFC3339 format
150 2006-01-02T15:04:05-07:00
151 --end=END
153 Set when the alert should should end. RFC3339 format
154 2006-01-02T15:04:05-07:00
155 --annotation=ANNOTATION
157 Set an annotation to be included with the alert
158 silence add [<flags>] [<matcher-groups>...]
160 Add a new alertmanager silence
161 This statement will add a silence that matches alerts with the
165 alertname=foo and node=bar label value pairs set.
166 If alertname is omitted and the first argument does not contain a
169 '=' or a '=~' then it will be assumed to be the value of the
170 alertname pair.
171 As well as direct equality, regex matching is also supported. The
174 '=~' syntax (similar to Prometheus) is used to represent a regex
175 match. Regex matching can be used in combination with a direct
176 match.
177 -a, --author=AUTHOR
180 Username for CreatedBy field
181 -d, --duration="1h"
183 Duration of silence
184 --start=START
186 Set when the silence should start. RFC3339 format
187 2006-01-02T15:04:05-07:00
188 --end=END
190 Set when the silence should end (overwrites duration). RFC3339
191 format 2006-01-02T15:04:05-07:00
192 -c, --comment=COMMENT
194 A comment to help describe the silence
195 silence expire [<silence-ids>...]
197 expire an alertmanager silence
198 silence import [<flags>] [<input-file>]
200 Import alertmanager silences from JSON file or stdin
201 This command can be used to bulk import silences from a JSON file cre‐
203 ated by query command. For example:
204 amtool silence query -o json foo > foo.json
206 amtool silence import foo.json
208 JSON data can also come from stdin if no param is specified.
210 -f, --force
213 Force adding new silences even if it already exists
214 -w, --worker=8
216 Number of concurrent workers to use for import
217 silence query [<flags>] [<matcher-groups>...]
219 Query Alertmanager silences.
220 Amtool has a simplified prometheus query syntax, but contains robust
222 support for bash variable expansions. The non-option section of argu‐
223 ments constructs a list of "Matcher Groups" that will be used to filter
224 your query. The following examples will attempt to show this behaviour
225 in action:
226 amtool silence query alertname=foo node=bar
228 This query will match all silences with the alertname=foo and
230 node=bar label value pairs set.
231 amtool silence query foo node=bar
233 If alertname is omitted and the first argument does not contain a
235 '=' or a '=~' then it will be assumed to be the value of the
236 alertname pair.
237 amtool silence query 'alertname=~foo.*'
239 As well as direct equality, regex matching is also supported. The
241 '=~' syntax (similar to prometheus) is used to represent a regex
242 match. Regex matching can be used in combination with a direct
243 match.
244 In addition to filtering by silence labels, one can also query for si‐
246 lences that are due to expire soon with the "--within" parameter. In
247 the event that you want to preemptively act upon expiring silences by
248 either fixing them or extending them. For example:
249 amtool silence query --within 8h
251 returns all the silences due to expire within the next 8 hours. This
253 syntax can also be combined with the label based filtering above for
254 more flexibility.
255 The "--expired" parameter returns only expired silences. Used in combi‐
257 nation with "--within=TIME", amtool returns the silences that expired
258 within the preceding duration.
259 amtool silence query --within 2h --expired
261 returns all silences that expired within the preceding 2 hours.
263 --expired
266 Show expired silences instead of active
267 -q, --quiet
269 Only show silence ids
270 --within=WITHIN
272 Show silences that will expire or have expired within a duration
273 silence update [<flags>] [<update-ids>...]
275 Update silences
276 -q, --quiet
278 Only show silence ids
279 -d, --duration=DURATION
281 Duration of silence
282 --start=START
284 Set when the silence should start. RFC3339 format
285 2006-01-02T15:04:05-07:00
286 --end=END
288 Set when the silence should end (overwrites duration). RFC3339
289 format 2006-01-02T15:04:05-07:00
290 -c, --comment=COMMENT
292 A comment to help describe the silence
293 check-config [<check-files>...]
295 Validate alertmanager config files
296 Will validate the syntax and schema for alertmanager config file and
298 associated templates. Non existing templates will not trigger errors.
299 cluster show
302 View cluster status and peers.
303 config show
305 View current config.
306 The amount of output is controlled by the output selection flag: -
308 Simple: Print just the running config - Extended: Print the run‐
309 ning config as well as uptime and all version info - Json: Print
310 entire config object as json
311 config routes show
314 Prints alert routing tree
315 Will print whole routing tree in form of ASCII tree view.
317 Routing is loaded from a local configuration file or a running Alert‐
319 manager configuration. Specifying --config.file takes precedence over
320 --alertmanager.url.
321 Example:
323 amtool config routes [show] --config.file=doc/examples/simple.yml
325 config routes test [<flags>] [<labels>...]
329 Test alert routing
330 Will return receiver names which the alert with given labels resolves
332 to. If the labelset resolves to multiple receivers, they are printed
333 out in order as defined in the routing tree.
334 Routing is loaded from a local configuration file or a running Alert‐
336 manager configuration. Specifying --config.file takes precedence over
337 --alertmanager.url.
338 Example:
340 amtool config routes test --config.file=doc/examples/simple.yml --ver‐
342 ify.receivers=team-DB-pager service=database
343 --verify.receivers=VERIFY.RECEIVERS
347 Checks if specified receivers matches resolved receivers. The
348 command fails if the labelset does not route to the specified
349 receivers.
350 --tree Prints out matching routes tree.
352 template render --template.glob=TEMPLATE.GLOB --template.text=TEMPLATE.TEXT
354 [<flags>]
355 Render a given definition in a template file to standard output.
356 --template.glob=TEMPLATE.GLOB
358 Glob of paths that will be expanded and used for rendering.
359 --template.text=TEMPLATE.TEXT
361 The template that will be rendered.
362 --template.type=TEMPLATE.TYPE
364 The type of the template. Can be either text (default) or html.
365 --template.data=TEMPLATE.DATA
367 Full path to a file which contains the data of the alert(-s)
368 with which the --template.text will be rendered. Must be in
369 JSON. File must be formatted according to the following layout:
370 https://pkg.go.dev/github.com/prometheus/alertmanager/tem‐
371 plate#Data. If none has been specified then a predefined, simple
372 alert will be used for rendering.
373version amtool, amtool(1)