Notifications as Code 1.0 (Legacy)

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.

🚧

Notifications 2.0

This document describes the format for notifications as code when using Notifications 1.0 (Legacy). These are available to customers created before December 2023, that have not completed their transition to Notifications 2.0. If you are using Notifications 2.0, read Notifications as Code 2.0.

If you plan to migrate from existing Notifications 1.0 settings to 2.0, you can add a version: "2" field on 2.0 style settings (for slack and email only) to create them while still having 1.0 active.

Please refer to the differences between Notifications 1.0 and 2.0, especially the functionality which is no longer supported. The largest change when migrating from Notifications as Code 1.0 (Legacy) is that each recipient may now only specify a single audience string. The old audiences list must be updated as follows:

• If audiences contains only 1 item, change it to audience: <single_audience_name>
• If audiences contains multiple items, you will need to create a separate recipient for each individual audience, each with audience: <single_audience_name>

Once you activate Notifications 2.0, your 1.0 definitions will start causing schema validation errors when applied, and will need to be removed from your Notification as Code files. You can either leave the version: "2" field on your settings or remove, as it will be ignored once you are using Notifications 2.0.

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 of audiences for which the channel should be used.

Note that audiences inside of a notifications definition is referenced as labels in a monitor definition. labels and audiences are equivalent, but some cases still require the term labels.

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

montecarlo:
  notifications:
    slack:
      - name: a-slack-notification
        channel: a-test-channel
        audiences: ['team-1', 'team-2']
    email:
      - name: a-email-notification
        emails: ['[email protected]', '[email protected]']
        audiences: ['team-1']
  field_health:
    - table: project:dataset.table_name
      timestamp_field: created
      labels: # monitors use the term labels, but they are equivalent to audiences
        - team-1

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
        channel: <string>        # required
        is_private: <bool>       # optional - defaults to false, pass true to use a slack private channel 
        custom_message: <string> # optional - a message to show with the notification
        audiences:               # required - the audiences to match
          - <string>
    email:
      - name: <string>           # required
        emails:                  # required - one or more recipients email
          - <string> 
        custom_message: <string> # optional - a message to show with the notification
        audiences:               # required - the audiences to match
          - <string>

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).
• custom_message: A custom message to show with the notification.
• 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.
• audiences: List of audiences for the notification. Only incidents for monitors with these audiences will be forwarded. At least one audience must be provided.

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).
• custom_message: A custom message to show with the notification.
• emails: A list of emails to send the notifications to.
• audiences: List of audiences for the notification. Only incidents for monitors with these audiences will be forwarded. At least one audience must be provided.