Notifications as Code 2.0

Overview

This guide explains how to use your Monitor as Code configuration files to setup Slack and Email notifications channels for custom monitors. Note: currently, only notifications from custom monitors are supported through Notifications as Code.

Prerequisites

1. Follow the instructions on the Monitors as Code: Prerequisites section to configure your CLI
2. Setup your project file as described on Monitors as code: Using code to define monitors

Defining notifications channels

In an existing monitor config file, or a new separate config file, add a notifications section to declare your channels. For each channel, indicate a name to uniquely identify the setting, the recipients, and a set the audience intended for the channel.

To associate a monitor to an audience, you will need to add it as a label of the monitor under labels in the monitor definition.

Here's an example with all the currently supported channels, including a monitor definition leveraging the defined audience:

montecarlo:
  notifications:
    slack:
      - name: a-slack-notification
        channel: a-test-channel
        audience: team-1
    email:
      - name: a-email-notification
        emails: ['[email protected]', '[email protected]']
        audience: team-3
  field_health:
    - table: project:dataset.table_name
      timestamp_field: created
      # label the monitor with the audience to ensure its incidents are routed to the associated
      channels
      labels: ['team-1', 'team-2']

The notifications section can be declared on a file that already contains monitor definitions, or on a separate file.

Notifications created through notifications as code will use the same namespace as the other monitors. You can get more information on namespaces here.

If the provided audiences do not exists, they will be created.

👍

Applying notification changes

Notification changes are applied with the same command as monitors. See Monitors as Code: Developing and testing locally for details.

Notifications configuration reference

montecarlo:
  notifications:
    slack:
      - name: <string>           # required
        audience: <string>       # required - the audience the channel belongs to
        channel: <string>        # required
        is_private: <bool>       # optional - defaults to false, pass true to use a slack private channel 
        version: "2"             # optional - used only when migrating from notifications 1.0
    email:
      - name: <string>           # required
        audience: <string>       # required - the audience the channel belongs to
        emails:                  # required - one or more recipient email
          - <string> 
			  version: "2"             # optional - used only when migrating from notifications 1.0

Slack

• name: Required value to uniquely identify the notification setting (to determine whether to create a new one or update an existing one for the namespace).
• audience: The audience the channel belongs to. The monitor must be labeled with this audience to get its incidents notifications routed to the associated channels.
• channel: The slack channel name for public channels, or the Slack channel ID for private ones. The channel must exist.
• is_private: Set to true when sending notifications to a private Slack channel. The channel should include the channel ID instead of the name.
• version: Only allowed value is "2". Is used to mark this setting as a notification 2.0 setting. Can be used to create 2.0 notifications alongside 1.0 ones while migrating to 2.0.

Email

• name: Required value to uniquely identify the notification setting (to determine whether to create a new one or update an existing one for the namespace).
• audience: The audience the channel belongs to. The monitor must be labeled with this audience to get its incidents notifications routed to the associated channels.
• emails: A list of emails to send the notifications to.
• version: Only allowed value is "2". Is used to mark this setting as a notification 2.0 setting. Can be used to create 2.0 notifications alongside 1.0 ones while migrating to 2.0.