amtool(1)

NAME
promtool - Tooling for the Prometheus alert manager

SYNOPSIS

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

DESCRIPTION
View and modify the current Alertmanager state.

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 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"

OPTIONS

-h, --help
    Show context-sensitive help (also try --help-long and --help-man).

--date.format="2006-01-02 15:04:05 MST"
    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)

--version
    Show application version.

COMMANDS

  help [<command>...]

Show help.

  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.

-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)

  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.

-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:05Z07:00

--end=END
    Set when the silence should end (overwrites duration). RFC3339 format 2006-01-02T15:04:05Z07:00

-c, --comment=COMMENT
    A comment to help describe the silence

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

expire an alertmanager silence

  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.

-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.

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 preceeding 2 hours.

--expired
    Show expired silences instead of active

-q, --quiet
    Only show silence ids

--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:05Z07:00

--end=END
    Set when the silence should end (overwrites duration). RFC3339 format 2006-01-02T15:04:05Z07:00

-c, --comment=COMMENT
    A comment to help describe the silence

  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.

  config

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