AMTOOL(1)

📦
version 0.33.1 · 14 versions
, in ubuntu stonking

💅 NAME 💅

amtool — Tooling for the Prometheus alert manager ✨

🌸 SYNOPSIS 🌸

amtool [<flags>] <command> [<args> ...]

🦋 DESCRIPTION 🦋

Bestie, amtool is literally here so you can view and modify the current Alertmanager state. It's giving main character energy. 💅

Config File: The alertmanager tool will read a config file in YAML format from one of two default config locations: $HOME/.config/prometheus/amtool.yml or /etc/prometheus/amtool.yml. 🗂️

All flags can be given in the config file, but the following are the ones suited for static configuration:

  • alertmanager.url — set a default alertmanager url for each request 🌐
  • author — set a default author value for new silences. If this argument is not specified then the username will be used ✍️
  • require-comment — Bool, whether to require a comment on silence creation. Defaults to true ✅
  • output — set a default output type. Options are (simple, extended, json) 🎨
  • date.format — sets the output format for dates. Defaults to "2006-01-02 15:04:05 MST" 📅
  • http.config.file — HTTP client configuration file for amtool to connect to Alertmanager. The format is https://prometheus.io/docs/alerting/latest/configuration/#http_config. 🔌

👑 OPTIONS 👑

  • -h, --help — Show context-sensitive help (also try --help-long and --help-man). 🆘
  • --date.format — Format of date output 📅
  • -v, --verbose — Verbose running information 🔊
  • --alertmanager.url=http://localhost:9093/ — Alertmanager to talk to 💬
  • -o, --output=simple — Output formatter (simple, extended, json) 🎨
  • --timeout=30s — Timeout for the executed command ⏳
  • --http.config.file=<filename> — HTTP client configuration file for amtool to connect to Alertmanager. 🔌
  • --version-check — Check alertmanager version. Use --no-version-check to disable. 🔍
  • --enable-feature — Experimental features to enable, comma separated. Valid options: alert-names-in-metrics, receiver-name-in-metrics, group-key-in-metrics, classic-mode, utf8-strict-mode, auto-gomemlimit, event-recorder 🧪
  • --version — Show application version. 📦

🎀 COMMANDS 🎀

okay bestie, this is the actual main character section — every single subcommand amtool ships with. no skipping, no skimming, we're going through all of them together 💖

💬 help [<command>...]

Show help.

that's it, that's the whole vibe. ask for help, receive help. iconic. ✨

🚨 alert query [<flags>] [<matcher-groups>...]

View and search through current alerts.

Amtool has a simplified prometheus query syntax, but contains robust support for bash variable expansions. The non-option section of arguments constructs a list of "Matcher Groups" that will be used to filter your query. The following examples will attempt to show this behaviour in action:

amtool alert query alertname=foo node=bar

This query will match all alerts with the alertname=foo and node=bar label value pairs set.

amtool alert query foo node=bar

If alertname is omitted and the first argument does not contain a = or a =~ then it will be assumed to be the value of the alertname pair.

amtool alert query 'alertname=~foo.*'

As well as direct equality, regex matching is also supported. The =~ syntax (similar to prometheus) is used to represent a regex match. Regex matching can be used in combination with a direct match.

Amtool supports several flags for filtering the returned alerts by state (inhibited, silenced, active, unprocessed). If none of these flags is given, only active alerts are returned. so like, pick your fighter or just vibe with the default 🌸

  • -i, --inhibited — Show inhibited alerts
  • -s, --silenced — Show silenced alerts
  • -a, --active — Show active alerts
  • -u, --unprocessed — Show unprocessed alerts
  • -r, --receiver=RECEIVER — Show alerts matching receiver (Supports regex syntax)

➕ alert add [<flags>] [<labels>...]

Add a new alert.

This command is used to add a new alert to Alertmanager.

To add a new alert with labels:

amtool alert add alertname=foo node=bar

If alertname is omitted and the first argument does not contain a = then it will be assumed to be the value of the alertname pair.

amtool alert add foo node=bar

One or more annotations can be added using the --annotation flag:

amtool alert add foo node=bar
     --annotation=runbook='http://runbook.biz'
    --annotation=summary='summary of the alert'
  --annotation=description='description of the alert'

Additional flags such as --generator-url, --start, and --end are also supported. (yes bestie, those are the next three right here, we love a callback 💅)

  • --generator-url=GENERATOR-URL — Set the URL of the source that generated the alert
  • --start=START — Set when the alert should start. RFC3339 format 2006-01-02T15:04:05-07:00
  • --end=END — Set when the alert should end. RFC3339 format 2006-01-02T15:04:05-07:00
  • --annotation=ANNOTATION — Set an annotation to be included with the alert

🔇 silence add [<flags>] [<matcher-groups>...]

Add a new alertmanager silence

This statement will add a silence that matches alerts with the alertname=foo and node=bar label value pairs set.

If alertname is omitted and the first argument does not contain a = or a =~ then it will be assumed to be the value of the alertname pair.

As well as direct equality, regex matching is also supported. The =~ syntax (similar to Prometheus) is used to represent a regex match. Regex matching can be used in combination with a direct match. shhhh time 🤫

  • -a, --author=AUTHOR — Username for CreatedBy field
  • -d, --duration="1h" — Duration of silence
  • --start=START — Set when the silence should start. RFC3339 format 2006-01-02T15:04:05-07:00
  • --end=END — Set when the silence should end (overwrites duration). RFC3339 format 2006-01-02T15:04:05-07:00
  • -c, --comment=COMMENT — A comment to help describe the silence
  • --annotation=ANNOTATION — Set an annotation to be included with the silence
lowkey important: --end overwrites --duration, so don't set both and expect the duration to win, because it will not. 🫶

⏳ silence expire [<silence-ids>...]

expire an alertmanager silence

feed it silence IDs and those silences get yeeted into the expired pile. bye bestie 👋

📥 silence import [<flags>] [<input-file>]

Import alertmanager silences from JSON file or stdin

This command can be used to bulk import silences from a JSON file created by query command. For example:

amtool silence query -o json foo > foo.json

amtool silence import foo.json

JSON data can also come from stdin if no param is specified. pipes stay winning 🌈

  • -f, --force — Force adding new silences even if it already exists
  • -w, --worker=8 — Number of concurrent workers to use for import

🔍 silence query [<flags>] [<matcher-groups>...]

Query Alertmanager silences.

Amtool has a simplified prometheus query syntax, but contains robust support for bash variable expansions. The non-option section of arguments constructs a list of "Matcher Groups" that will be used to filter your query. The following examples will attempt to show this behaviour in action:

amtool silence query alertname=foo node=bar

This query will match all silences with the alertname=foo and node=bar label value pairs set.

amtool silence query foo node=bar

If alertname is omitted and the first argument does not contain a = or a =~ then it will be assumed to be the value of the alertname pair.

amtool silence query 'alertname=~foo.*'

As well as direct equality, regex matching is also supported. The =~ syntax (similar to prometheus) is used to represent a regex match. Regex matching can be used in combination with a direct match.

In addition to filtering by silence labels, one can also query for silences that are due to expire soon with the --within parameter. In the event that you want to preemptively act upon expiring silences by either fixing them or extending them. For example:

amtool silence query --within 8h

returns all the silences due to expire within the next 8 hours. This syntax can also be combined with the label based filtering above for more flexibility. mix and match, it's giving customizable ✨

The --expired parameter returns only expired silences. Used in combination with --within=TIME, amtool returns the silences that expired within the preceding duration.

amtool silence query --within 2h --expired

returns all silences that expired within the preceding 2 hours.

  • --expired — Show expired silences instead of active
  • -q, --quiet — Only show silence ids
  • --created-by=CREATED-BY — Show silences that belong to this creator
  • --id=ID — Get a single silence by its ID
  • --within=WITHIN — Show silences that will expire or have expired within a duration

✏️ silence update [<flags>] [<update-ids>...]

Update silences

  • -q, --quiet — Only show silence ids
  • -d, --duration=DURATION — Duration of silence
  • --start=START — Set when the silence should start. RFC3339 format 2006-01-02T15:04:05-07:00
  • --end=END — Set when the silence should end (overwrites duration). RFC3339 format 2006-01-02T15:04:05-07:00
  • -c, --comment=COMMENT — A comment to help describe the silence
same warning as before bestie: --end overwrites duration. do not fight it. 💀

✅ check-config [<check-files>...]

Validate alertmanager config files

Will validate the syntax and schema for alertmanager config file and associated templates. Non existing templates will not trigger errors. it's like a vibe check but for YAML 👑

🌐 cluster show

View cluster status and peers.

see who's in the group chat — sorry, the cluster. 🦋

⚙️ config show

View current config.

The amount of output is controlled by the output selection flag:

  • Simple: Print just the running config
  • Extended: Print the running config as well as uptime and all version info
  • Json: Print entire config object as json

🌳 config routes show

Prints alert routing tree

Will print whole routing tree in form of ASCII tree view.

Routing is loaded from a local configuration file or a running Alertmanager configuration. Specifying --config.file takes precedence over --alertmanager.url.

Example:

amtool config routes [show] --config.file=doc/examples/simple.yml

🧪 config routes test [<flags>] [<labels>...]

Test alert routing

Will return receiver names which the alert with given labels resolves to. If the labelset resolves to multiple receivers, they are printed out in order as defined in the routing tree.

Routing is loaded from a local configuration file or a running Alertmanager configuration. Specifying --config.file takes precedence over --alertmanager.url.

Example:

amtool config routes test --config.file=doc/examples/simple.yml
--verify.receivers=team-DB-pager service=database
  • --verify.receivers=VERIFY.RECEIVERS — Checks if specified receivers matches resolved receivers. The command fails if the labelset does not route to the specified receivers.
  • --tree — Prints out matching routes tree.

🧚 template render --template.glob=TEMPLATE.GLOB --template.text=TEMPLATE.TEXT [<flags>]

Render a given definition in a template file to standard output.

  • --template.glob=TEMPLATE.GLOB — Glob of paths that will be expanded and used for rendering.
  • --template.text=TEMPLATE.TEXT — The template that will be rendered.
  • --template.type=TEMPLATE.TYPE — The type of the template. Can be either text (default) or html.
  • --template.data=TEMPLATE.DATA — Full path to a file which contains the data of the alert(-s) with which the --template.text will be rendered. Must be in JSON. File must be formatted according to the following layout: https://pkg.go.dev/github.com/prometheus/alertmanager/template#Data. If none has been specified then a predefined, simple alert will be used for rendering.

that's the whole page bestie, you made it to the end and honestly? ate. 💅🎀

this was prometheus-alertmanager 0.33.1, dated August 2026, answering to the name AMTOOL(1) — go forth and query, add, silence, expire, import, update, check, show, test and render, you absolute legend 💖🌈✨

📦 where this page comes from