Configuration

In this lesson we walk through an Alertmanager configuration file (alertmanager.yml) and explain how to route alerts to the right receivers. A typical Alertmanager configuration uses three primary sections:

global — default settings applied across receivers (overridable).
route — routing tree that maps alerts to receivers.
receivers — notification destinations (Slack, email, SMS, webhooks, etc.).

Below is a compact, representative configuration that shows these sections together:

global:
  smtp_smarthost: 'mail.example.com:25'
  smtp_from: 'test@example.com'

route:
  receiver: staff
  group_by: ['alertname', 'job']
  routes:
    - match_re:
        job: "(node|windows)"
      receiver: infra-email

    - match:
        job: kubernetes
        severity: ticket
      receiver: k8s-slack

receivers:
  - name: 'k8s-slack'
    slack_configs:
      - channel: '#alerts'
        text: 'https://example.com/alerts/{{ .GroupLabels.app }}'
  - name: 'infra-email'
    email_configs:
      - to: 'infra@example.com'
  - name: 'staff'
    email_configs:
      - to: 'staff@example.com'

This sample illustrates the core concepts: defaults in global, a routing tree beginning at route, and concrete receivers that deliver notifications. Callout for quick context:

This guide focuses on Alertmanager routing: how alerts flow from the top-level route into nested routes, and how receivers and grouping control notification behavior.

global

The global block sets defaults used by receiver configurations (for example, SMTP settings). Any receiver that lacks its own explicit setting will inherit values from global. Common uses include SMTP relay host, email from address, and generic webhook configuration defaults.

route

The route section defines the routing tree that decides which alerts are sent to which receivers. At the top level, define a fallback receiver using the top-level receiver field. Alerts that do not match a more specific child route will continue to the fallback. Example default/fallback route:

route:
  receiver: staff
  group_by: ['alertname', 'job']
  routes:
    - match_re:
        job: "(node|windows)"
      receiver: infra-email
    - match:
        job: kubernetes
      receiver: k8s-slack

Key route fields:

receiver — the default receiver to send alerts to.
group_by — labels used to group alerts into single notifications.
routes — array of child routes, evaluated in order.

Matcher types

Alertmanager supports three common matcher syntaxes. Use the one that best matches your routing needs.

Matcher syntax	Use case	Example
`match`	Exact label equality (all listed pairs must match)	`match: { job: kubernetes, severity: ticket }`
`match_re`	Label values matched by regular expressions (useful to match multiple values)	`match_re: { job: "(node\|windows)" }`
`matchers`	Array of expressions with operators and regex (`=`, `!=`, `=~`, `!~`)	`matchers: ['severity="page"', 'env=~"prod\|staging"']`

Example combining exact and regex matching:

route:
  routes:
    - match_re:
        job: "(node|windows)"
      receiver: infra-email

    - match:
        job: kubernetes
        severity: ticket
      receiver: k8s-slack

Sub-routes (nested routes)

Routes can be nested to create parent → child relationships. Matching begins at the top-level route and then descends into child routes. A child route is only considered if its parent route matches. Example: parent route matches job: kubernetes; a child route matches severity: pager and overrides the receiver:

route:
  receiver: k8s-email
  routes:
    - match:
        job: kubernetes
      receiver: k8s-email
      routes:
        - match:
            severity: pager
          receiver: k8s-pager

Behavior:

Alerts with job=kubernetes and severity=pager will route to k8s-pager.
Alerts with job=kubernetes but without severity=pager will use k8s-email (the parent route receiver).

Example: multiple teams and sub-routes

Below is a practical layout for routing alerts to different teams (database and API), with sub-routes for severities and environments:

route:
  receiver: fallback-pager
  routes:
    # database team
    - match:
        team: database
      receiver: database-pager
      routes:
        - match:
            severity: page
          receiver: database-pager
        - match:
            severity: email
          receiver: database-email

    # api team
    - match:
        team: api
      receiver: api-pager
      routes:
        - match:
            severity: page
            env: dev
          receiver: api-ticket
        - match:
            severity: page
          receiver: api-pager
        - match:
            severity: ticket
          receiver: api-ticket

Notes on evaluation:

The parent route (e.g., team: database) determines the initial receiver if no child route matches.
Child routes are evaluated in order and can override the parent receiver if matched.

Reloading configuration

Alertmanager does not automatically reload changes to alertmanager.yml. After editing the file you must apply the update using one of these methods:

Restart the Alertmanager process (systemd example):
- sudo systemctl restart alertmanager
Send a SIGHUP to the process:
- sudo killall -HUP alertmanager
POST to the reload endpoint:
- curl -X POST http://localhost:9093/-/reload

Always validate your YAML before reloading. A malformed configuration can prevent Alertmanager from starting or handling alerts correctly.

Continue behavior (allowing multiple matches)

By default, route traversal stops when a route matches (first match wins). If you want an alert to match a route and then continue to later routes (so the same alert is delivered to multiple receivers), set continue: true on the route that should allow further evaluation. Example — send every alert to alert-logs, and also to k8s-email for Kubernetes alerts:

route:
  routes:
    - receiver: alert-logs
      continue: true

    - match:
        job: kubernetes
      receiver: k8s-email

Grouping alerts

Alertmanager groups alerts for a route into a single notification by default. Use group_by to control batching. Child routes inherit group_by from their parent unless they define their own. Top-level grouping by team:

route:
  receiver: fallback-pager
  group_by: ['team']
  routes:
    - match:
        team: infra
      group_by: ['region', 'env']
      receiver: infra-email
      routes:
        - match:
            severity: page
          receiver: infra-pager

Behavior:

Top-level: alerts are grouped by team. Alerts with the same team value are batched into single notifications.
For the infra route: grouping refines to region and env. Alerts with the same region and env values are grouped together.

Best practices and final reminders

Keep global, route, and receivers sections well organized and consistent.
Use:
- match for exact label matches,
- match_re for regex-based matching,
- matchers for advanced matching expressions.
Use continue: true on routes when you intentionally want an alert to be handled by multiple receivers.
Validate YAML and reload Alertmanager after changes.
Use meaningful group_by labels to avoid noisy notifications or overly coarse grouping.

Links and references

Alertmanager Configuration — official Prometheus Alertmanager docs
Alertmanager Routing — routing tree and matcher details

If you need a sample repository or more advanced receiver examples (Slack webhooks, PagerDuty), check the official docs linked above for integration-specific fields and templates.

Introduction

Observability Fundamentals

Prometheus Fundamentals

PromQL

Dashboarding & Visualization

Application Instrumentation

Service Discovery

Push Gateway

Alerting

Monitoring Kubernetes

Conclusion

Scaling & Long Term Storage

global

route

Matcher types

Sub-routes (nested routes)

Example: multiple teams and sub-routes

Reloading configuration

Continue behavior (allowing multiple matches)

Grouping alerts

Best practices and final reminders

Links and references

Watch Video

​global

​route

​Matcher types

​Sub-routes (nested routes)

​Example: multiple teams and sub-routes

​Reloading configuration

​Continue behavior (allowing multiple matches)

​Grouping alerts

​Best practices and final reminders

​Links and references

Watch Video

global

route

Matcher types

Sub-routes (nested routes)

Example: multiple teams and sub-routes

Reloading configuration

Continue behavior (allowing multiple matches)

Grouping alerts

Best practices and final reminders

Links and references