# Alerter Configuration

Alerters send one-off alerts when a monitor fails. They can also send an alert when it succeeds again.

An alerter knows if it is urgent or not; if a monitor defined as non-urgent fails, an urgent alerter will not trigger for it. This means you can avoid receiving SMS alerts for things which don’t require your immediate attention.

Alerters can also have a time configuration for hours when they are or are not allowed to alert. They can also send an alert at the end of the silence period for any monitors which are currently failed.

Alerters are defined in the main configuration file, which by default is `monitor.ini`. The section name is the name of your alerter, which you should then add to the `alerters` configuration value.

## Common options

These options are common to all alerter types.

type
  Type:

    string

  Required:

    true

  the type of the alerter; one of those in the list below.

depend
  Type:

    comma-separated list of string

  Required:

    false

  Default:

    none

  a list of monitors this alerter depends on. If any of them fail, no attempt will be made to send the alert.

limit
  Type:

    integer

  Required:

    false

  Default:

    `1`

  the (virtual) number of times a monitor must have failed before this alerter fires for it. You can use this to escalate an alert to another email address or text messaging, for example. See the tolerance Monitor configuration option.

dry_run
  Type:

    boolean

  Required:

    false

  Default:

    false

  makes an alerter do everything except actually send the message, and instead will print some information about what it would do.

ooh_success
  Type:

    boolean

  Required:

    false

  Default:

    false

  makes an alerter trigger its success action even if out of hours

groups
  Type:

    comma-separated list of string

  Required:

    false

  Default:

    `default`

  list of monitor groups this alerter should fire for. See the group setting for monitors.

only_failures
  Type:

    boolean

  Required:

    false

  Default:

    false

  if true, only send alerts for failures (or catchups)

tz
  Type:

    string

  Required:

    false

  Default:

    `UTC`

  the timezone to use in alert messages. See also `times_tz`.

repeat
  Type:

    boolean

  Required:

    false

  Default:

    false

  fire this alerter (for a failed monitor) every iteration. See also `allow_reminders`.

urgent
  Type:

    boolean

  Required:

    false

  if the alerter should be urgent or not. The default varies from alerter to alerter. Typically, those which send “page” style alerts such as SMS default to urgent. You can use this option to override that in e.g. the case of the SNS alerter, which could be urgent if sending SMSes, but non-urgent if sending emails.

enabled
  Type:

    boolean

  Required:

    false

  Default:

    true

  Set to false to turn off the alerter

allow_reminders
  Type:

    boolean

  Required:

    false

  Default:

    false

  Set to true to allow this alerter to send reminders, for monitors configured for them (see `reminder`)

## Time restrictions

All alerters accept time period configuration. By default, an alerter is active at all times, so you will always immediately receive an alert at the point where a monitor has failed enough (more times than the limit). To set limits on when an alerter can send, use the configuration values below.

Note that the `times_type` option sets the timezone all the values are interpreted as. The default is the local timezone of the host evaluating the logic.

day
  Type:

    comma-separated list of integer

  Required:

    false

  Default:

    all days

  which days an alerter can operate on. `0` is Monday, `6` is Sunday.

times_type
  Type:

    string

  Required:

    false

  Default:

    `always`

  one of `always`, `only`, or `not`. `only` means that the limits specify the period the alerter is allowed to operate in. `not` means the specify the period it isn’t, and outside of that time it is allowed.

time_lower
  Type:

    string

  Required:

    when `times_type` is not `always`

  the lower end of the time range. Must be lower than `time_upper`. The format is `HH:mm` in 24-hour clock.

time_upper
  Type:

    string

  Required:

    when `times_type` is not `always`

  the upper end of the time range. Must be lower than `time_lower`. The format is `HH:mm` in 24-hour clock.

times_tz
  Type:

    string

  Required:

    false

  Default:

    the host’s local time

  the timezone for `day`, `time_lower` and `time_upper` to be interpreted in.

delay
  Type:

    boolean

  Required:

    false

  Default:

    false

  set to true to have the alerter send a “catch-up” alert about a failed monitor if it failed during a time the alerter was not allowed to send, and is still failed as the alerter enters the time it is allowed to send. If the monitor fails and recovers during the not-allowed time, no alert is sent either way.

### Time examples

These snippets omit the alerter-specific configuration values.

Don’t trigger during the hours I’m in the office (8:30am to 5:30pm, Monday to Friday):

    [out_of_hours]
    type=some-alerter-type
    times_type=not
    time_lower=08:30
    time_upper=17:30
    days=0,1,2,3,4

Don’t send at antisocial times, but let me know later if something broke and hasn’t recovered yet:

    [polite_alerter]
    type=some-alerter-type
    times_type=only
    time_lower=07:30
    time_upper=22:00
    delay=1

## Alerters

Note

The `type` of the alerter is the first word in its heading.

- 46elks - 46elks notifications
- bulksms - SMS via BulkSMS
- email - send via SMTP
- execute - run external command
- healthchecks - notifications
- nc - macOS notifications
- nextcloud_notification - notifications
- ntfy - ntfy notifications
- pushbullet - push notifications
- pushover - notifications
- ses - email via Amazon Simple Email Service
- slack - Slack webhook
- sms77 - SMS via sms77
- sns - Amazon Simple Notification Service
- syslog - send to syslog
- telegram - send to a chat
- twilio_sms - SMS via Twilio