amtool

Manage Prometheus Alertmanager from the command line

TLDR

List all current alerts

$ amtool alert

Query alerts matching a label

$ amtool alert query [alertname="HighMemory"]

Create a silence for an alert

$ amtool silence add [alertname="HighMemory"] --comment="[Maintenance]" --duration=[2h]

List all active silences

$ amtool silence query

Expire a silence by ID

$ amtool silence expire [silence_id]

Check Alertmanager configuration

$ amtool check-config [alertmanager.yml]

Show cluster status

$ amtool cluster show

SYNOPSIS

amtool command [options] [arguments]

amtool is the official command-line client for interacting with Prometheus Alertmanager. It provides capabilities for querying alerts, managing silences, testing routing configurations, and validating configuration files.The tool connects to an Alertmanager instance via its HTTP API to perform operations. It is particularly useful for creating silences during maintenance windows, debugging alert routing, and integrating Alertmanager management into automation scripts.Configuration can be validated offline using check-config without requiring a running Alertmanager instance. The config routes test command helps verify that alerts will be routed to expected receivers based on their labels.

PARAMETERS

alert query

View and search through current alerts.

alert add

Add a new alert to Alertmanager.

silence add matchers

Create a new silence matching the specified labels.

silence query

List active silences.

silence update id

Update an existing silence (e.g., extend its duration).

silence expire id

Remove a silence by its ID.

silence import

Import silences from a JSON file or stdin.

check-config file

Validate Alertmanager configuration files.

cluster show

Display cluster membership status and peers.

config show

Display the current Alertmanager configuration.

config routes show

Display routing tree from configuration.

config routes test labels

Test which route matches given labels.

template render

Render a template definition for testing.

--alertmanager.url url

Alertmanager URL (default: http://localhost:9093/).

--comment text

Comment for a silence (required unless configured otherwise).

--author name

Author of a silence (CreatedBy field).

--duration duration

Duration for a silence (default: 1h, e.g., 30m, 2h).

--end time

Set silence expiration as an RFC3339 timestamp.

--timeout duration

Timeout for API requests (default: 30s).

-o, --output format

Output format: simple, extended, json (default: simple).

CONFIGURATION

~/.config/amtool/config.yml

Persistent configuration for the Alertmanager URL, author, and output format defaults.

INSTALL

sudo apt install prometheus-alertmanager

sudo dnf install alertmanager

sudo pacman -S alertmanager

sudo apk add alertmanager

nix profile install nixpkgs#prometheus-alertmanager

CAVEATS

Requires network access to the Alertmanager API endpoint. Silences require a comment; creating them without --comment will fail. The --alertmanager.url must be specified if Alertmanager is not running on localhost:9093. Configuration file validation may not catch all runtime issues.

HISTORY

amtool was developed alongside Alertmanager as part of the Prometheus ecosystem. It was created to provide operators with a scriptable interface for alert management, complementing the web UI for automation and CI/CD integration. The tool is maintained by the Prometheus project and distributed as part of the Alertmanager release.

RESOURCES

Source code · Documentation