Notifications as Code

Overview

This guide explains how to use your Monitor as Code configuration files to setup 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 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, including a monitor definition leveraging the defined audience. See below for examples of other notification channels.

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 exist, 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:
    email:
      - name: <string>           # required
        audience: <string>       # required - the audience the channel belongs to
        emails:                  # required - one or more recipient email
          - <string>
    jira:
      - name: <string>           # required
        audience: <string>       # required - the audience the channel belongs to
        integration: <string> 	 # required - integration UUID or name
        project: <string>        # required - the Jira project ID to create the notification on 
        issue_type: <string>     # required - the Jira issue type ID to create the notification as
    msteams:
      - name: <string>           # required
        audience: <string>       # required - the audience the channel belongs to
        webhook_url: <string>    # required - Teams webhook URL
        receive_normalized: <bool> # optional - defaults to true
    opsgenie:
      - name: <string>           # required
        audience: <string>       # required - the audience the channel belongs to
        integration: <string>    # required - integration UUID or name
    pagerduty:
      - name: <string>           # required
        audience: <string>       # required - the audience the channel belongs to
        routing_key: <string>    # required - the routing key or a {secret:...} reference
    servicenow:
      - name: <string>           # required
        audience: <string>       # required - the audience the channel belongs to
        integration: <string>    # required - integration UUID or name    
        fields: <dict>           # optional - required fields to populate for the notification
    slack:
      - name: <string>           # required
        audience: <string>       # required - the audience the channel belongs to
        channel: <string>        # required - the Slack channel to notify
        is_private: <bool>       # optional - defaults to false, pass true to use a slack private 
                                 # channel 
    webex:
      - name: <string>           # required
        audience: <string>       # required - the audience the channel belongs to
        integration: <string>    # required - integration UUID or name 
        room: <string>           # required - Webex room name
    webhook:
      - name: <string>           # required
        audience: <string>       # required - the audience the channel belongs to
        url: <string>            # required - the webhook endpoint
        secret: <string>         # optional - a secret to sign the requests with or 
                                 # a {secret:...} reference                                 
    google_chat:
      - name: <string>           # required
        audience: <string>       # required - the audience the channel belongs to
        webhook_url: <string>    # required - the google chat space webhook endpoint

Common attributes

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

Email

• emails: A list of emails to send the notifications to.

Jira

See Jira for an intro into Jira notifications, and how to configure the integration.

• integration: The UUID or name of a Jira integration configured on your account.
• project: A Jira Project ID to add the ticket to. At the moment you need to provide the actual ID, not the name/title of the project. See the Jira documentation for information on how to find this value.
• issue_type: A Jira Issue Type ID to add the ticket as. The issue type must be valid in the context of the provided project. At the moment you need to provide the actual ID, not the name/title of the issue type.

Microsoft Teams

See MS Teams for an intro into MS Teams notifications.

• webhook_url: The Team Webhook URL. See the Microsoft Teams documentation on how to obtain one for your Teams channel.
• receive_normalized: If true normalized incident notifications will be sent to the channel. Defaults to true.

Opsgenie

See Opsgenie for an intro into Opsgenie notifications.

• integration: The UUID or name of a Opsgenie integration configured on your account.

PagerDuty

See PagerDuty for an intro into PagerDuty notifications.

• routing_key: The PagerDuty routing key. You can provide the key in plain text, or use a {secret:...} reference to load the routing key from the provided secret. The secret must be in the notifications or global scope. See Secret management with the CLI for additional information.

ServiceNow

See ServiceNow for an intro to ServiceNow notifications, and how to configure your integration.

• integration: The UUID or name of a ServiceNow integration configured on your account.
• fields: A dictionary of field name to value. Used to populate required fields when creating the Service Now issue.

Slack

See Slack for an intro to Slack notifications.

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

Webex

See Webex for an intro to Webex notifications, and how to configure your integration.

• integration: The UUID or name of a Webex integration configured on your account.
• room: The name of the Webex room.

Webhook

See Webhooks for an intro to Webhook notifications.

• url: The webhook URL where to post the notification.
• secret: A secret used to sign the webhook HTTP request. You can provide the secret in plain text, or use a {secret:...} reference to load the secret from the provided secret. The secret must be in the notifications or global scope. See Secret management with the CLI for additional information.

Google Chat

See Google Chat for an intro to Google Chat notifications.

• webhook_url: The google chat space webhook URL where to post the notification.