Managing notification channels

This page lists the supported notification channel types available for Cloud Monitoring alerting policies and explains how to configure them by using the Google Cloud Console. To configure notification channels by using the Cloud Monitoring API, see Managing notification channels.

For information about alerting-policy notifications, see the following pages:

By default, an alerting policy sends a notification only when an incident is created. To receive a notification when the incident is opened and when it is closed, edit the alerting policy and, in the notifications section, select Notify on incident closure.

Creating channels

To configure a notification channel, you must have one of the following Identity and Access Management roles on the scoping project of a metrics scope:

  • Monitoring NotificationChannel Editor
  • Monitoring Editor
  • Monitoring Admin
  • Project Editor
  • Project Owner

For more information about these roles, see Access control.

When you are creating an alerting policy, you can select any configured notification channel and add it to your policy. You can pre-configure your notification channels, or you can configure them as part of the process of creating an alerting policy. For more information, see Creating a channel on demand.

To create a notification channel by using the Cloud Console, do the following:

  1. In the Cloud Console, use the project picker to select your Google Cloud project, and then select Monitoring, or click the following button:

    Go to Monitoring

  2. In the Monitoring navigation pane, click Alerting.

  3. Click Edit notification channels.

  4. To add a new notification channel, locate the channel type, click Add new, and then follow the channel-specific instructions contained in the following table:

Email

To add an email, go to the Email section, click Add new, and follow the instructions.

You can create email channels during the creation of an alerting policy. For more information, see Creating a channel on demand.

If you use a group email address as the notification channel for an alerting policy, then configure the group to accept mail from alerting-noreply@google.com.

Mobile App

Use the Cloud Console Mobile App to monitor your Cloud Console resources and Monitoring information from anywhere.

To configure a Cloud Console Mobile App notification channel for a specific Google Cloud project, do the following:

  1. Install the Cloud Console Mobile App from your mobile device's app store.
  2. Select a project for viewing in the Cloud Console Mobile App. This action results in a data exchange between the app and the selected Google Cloud project. A notification channel is created automatically when one doesn't exist, and after a few minutes, this channel is listed under the Mobile Devices section of the Notification channels page.

To add your mobile device as a notification channel for an alerting policy, in the alerting Notifications section, select Google Cloud Console (mobile) and then choose your mobile device from the list.

Understanding what devices are notified

In the Mobile Devices section of the Notification channels page, the Scope column specifies where notifications are sent:

List of Cloud Console Mobile App} notification channels.

  • Device indicates that notifications are sent only to the specific device that created the notification channel. For device-scoped notification channels, the Display name field includes device information.
  • User indicates that the notifications are sent to all of your devices that have the Cloud Console Mobile App installed.

Cloud Monitoring determines the notification scope when the channel is created. You can't select or change the scope.

PagerDuty

Integration with PagerDuty allows for one-way or two-way synchronization with Monitoring. Independent of your configuration, the following are true:

  • If an incident is created in Monitoring, then an incident is opened in PagerDuty.
  • You can't use PagerDuty to close an incident in Monitoring.

If you use one-way synchronization and if you resolve the incident in PagerDuty, then the state of the incident in PagerDuty is decoupled from the state of the incident in Monitoring. In effect, if you resolve an incident in PagerDuty, then the incident is permanently closed in PagerDuty and can't be reopened.

If you use two-way synchronization, then Monitoring controls the state shown by PagerDuty. If you resolve the incident in PagerDuty and if Monitoring has the incident open, then the incident is reopened in PagerDuty.

To set up PagerDuty notifications, do the following:

  1. In PagerDuty: Create a PagerDuty account at the PagerDuty site.
  2. Complete the integration between PagerDuty and Monitoring by following the steps outlined in PagerDuty's Stackdriver Integration Guide.
  3. In the Notification channels window of the Google Cloud Console, add a PagerDuty notification channel:
    1. In the PagerDuty section, click Add new.
    2. Enter the Display Name. This name should match the name provided to PagerDuty when you added the integration.
    3. Enter the Integration Service Key generated by PagerDuty into the Service Key field.
    4. Click Save.
  4. (Optional) If you want to configure two-way synchronization, then do the following:
    1. In PagerDuty, select Configuration and then Services and then the service name you entered when configuring the integration.
    2. Click Edit Settings and select Create incidents, and then clear Create alerts and incidents.

When you create an alerting policy, select PagerDuty in the Notifications section and choose your PagerDuty configuration.

In this document, the screenshots for Stackdriver are from an older version of Stackdriver, but the information is accurate.

SMS

To configure SMS notifications, do the following:

  1. In the SMS section, click Add new and follow the instructions.
  2. Click Save.

When you set up your alerting policy, select the SMS notification type and choose a verified phone number from the list.

Slack

The Monitoring Slack integration allows your alerting policies to post to a Slack channel when a new incident is created. To set up Slack notifications, do the following:

  1. In Slack: Create a Slack workspace and channel at the Slack site. Record the channel URL.

  2. In the Cloud Console, select Monitoring:

    Go to Monitoring

  3. Click Alerting and then click Edit notification channels.

  4. In the Slack section, click Add new to open the Slack sign-in page:

    1. Select your Slack workspace.
    2. Click Allow to enable Cloud Monitoring access to your Slack workspace. This action takes you back to the Monitoring configuration page for your notification channel.
    3. Enter the name of the Slack channel you want to use for notifications.
    4. Enter a display name for the Slack notification channel.
    5. (Optional) To test the connection between Cloud Monitoring and your Slack workspace, click Test connection. If the connection is successful, then you see a message This is a test alert notification... in the Slack notification channel that you specified.
  5. In Slack:

    1. Go to the channel you specified as your Monitoring notification channel.

    2. Invite the Monitoring app to the channel by sending the following message in the channel:

      /invite @Google Cloud Monitoring

      Be sure you invite the Monitoring app to the channel you specified when creating the notification channel in Monitoring.

    When you create an alerting policy, select Slack in the Notifications section and choose your Slack configuration.

Webhooks

Using Webhooks for notifications requires a public endpoint URL. To configure Webhooks notifications, do the following:

  1. The webhook handler: Identify the public endpoint URL to receive webhook data from Monitoring.
  2. In the Webhooks section, click Add new and follow the instructions.
  3. Click Test Connection to send a test payload to the Webhook endpoint. You can go to the receiving endpoint to verify delivery.
  4. Click Save.

When you create an alerting policy, select Webhook in the Notifications section and choose your webhook configuration.

Basic authentication

In addition to the webhook request sent by Cloud Monitoring, basic authentication utilizes the HTTP specification for the username and password. Cloud Monitoring requires your server to return a 401 response with the proper WWW-Authenticate header. For more information about basic authentication, see the following:

Token authentication

Token Authentication requires a query string parameter in the endpoint URL and a key that the server expects to be secret between itself and Monitoring. The following is a sample URL that includes a token:

https://www.myserver.com/stackdriver-hook?auth_token=1234-abcd

If Monitoring posts an incident to the endpoint URL, your server can validate the attached token. This method of authentication is most effective when used with SSL/TLS to encrypt the HTTP request preventing snoopers from learning the token.

For an example server in Python, see this sample server.

Deprecation policy

The payload schema is subject to the Google Cloud deprecation policy outlined in Section 1.4(d) of the Google Cloud Platform Terms of Service. Note that the schema does not control the formats of generated field values, and these formats can change without notice. For example, incident.summary, incident.documentation.content, and incident.url are meant to include data pertaining to their fields, but the schema doesn't have constraints to guarantee accurate parsing of these fields. You can consume the value as a whole and expect that it adheres to the deprecation policy, but don't rely on parsing the generated fields.

Pub/Sub

To send notifications to a Pub/Sub topic, do the following:

  1. Click the following button to enable the Pub/Sub API for your project:

    Enable Pub/Sub API

    1. Ensure that the correct Google Cloud project is selected.
    2. If an Enable button is displayed, then click that button.
    3. If API Enabled is displayed, then the API is already enabled.
  2. Create a Pub/Sub topic, as described in Creating a topic, if you don't already have one. The topic must exist before you can use it as a notification channel. The following command creates a topic called notificationTopic.

    gcloud pubsub topics create notificationTopic
  3. Create a notification channel that uses the topic. You can use the Monitoring API, the gcloud command-line tool, or the Cloud Console.

    To use the Cloud Console to create the notification channel, go to the Edit notification channels window and then do the following:

    1. In the Cloud Pub/Sub section, click Add new.
    2. Enter a display name for your channel, enter the Pub/Sub topic name, and then click Add channel.

    To use the Monitoring API or the gcloud command-line tool to create the notification channel, see Creating channels for information and examples.

  4. Authorize the notifications service account to publish to each Pub/Sub topic that you are using as a notification channel.

    When you create the first Pub/Sub channel, Cloud Monitoring creates a service account for the project in which the channel was created and grants the service account the Identity and Access Management role Monitoring Notification Service Agent. The service account lets Monitoring send notifications to Pub/Sub-based notification channels in this project.

    This service account has an ID with the following structure:

    service-[PROJECT_NUMBER]@gcp-sa-monitoring-notification.iam.gserviceaccount.com

    To see the service account, go to the IAM page:

    Go to IAM

    If the service account isn't displayed, try the following:

    • Select Include Google-provided role grants, as shown in the following screenshot:

      Select the **Include Google-provided role grants** option.

    • Reload the page.

    To authorize this account to publish to a topic, you must give the service account the pubsub.publisher IAM role for the topic. For example, the following command configures the IAM role for the notificationTopic topic:

    gcloud pubsub topics add-iam-policy-binding \
    projects/[PROJECT_NUMBER]/topics/notificationTopic --role=roles/pubsub.publisher \
    --member=serviceAccount:service-[PROJECT_NUMBER]@gcp-sa-monitoring-notification.iam.gserviceaccount.com
    

    If the command succeeds, it returns output like the following:

    Updated IAM policy for topic [notificationTopic].
    bindings:
    ‐ members:
      ‐ serviceAccount:service-[PROJECT_NUMBER]@gcp-sa-monitoring-notification.iam.gserviceaccount.com
      role: roles/pubsub.publisher
    etag: BwWcDOIw1Pc=
    version: 1
    

    For more information, see the pubsub topics add-iam-policy-binding reference page.

    The project number is not the same as the project ID. Project IDs are typically strings that reflect the project name, like my-test-project. Project numbers are unique numerical identifiers. You can find the project name, ID, and number on the project's landing page in the Cloud Console, or you can retrieve it with the following command:

    gcloud projects describe [PROJECT_ID] --format="value(project_number)"
    
  5. Add the Pub/Sub channel to an alerting policy by selecting Pub/Sub as the channel type and a named topic as the notification channel.

    Schema example

    To view an example JSON packet and the schema, expand the following sections.

    Deprecation policy

    The payload schema is subject to the Google Cloud deprecation policy outlined in Section 1.4(d) of the Google Cloud Platform Terms of Service. Note that the schema does not control the formats of generated field values, and these formats can change without notice. For example, incident.summary, incident.documentation.content, and incident.url are meant to include data pertaining to their fields, but the schema doesn't have constraints to guarantee accurate parsing of these fields. You can consume the value as a whole and expect that it adheres to the deprecation policy, but don't rely on parsing the generated fields.

Creating a channel on demand

When adding a notification channel to an alerting policy, you must select a channel from a list. If the list doesn't contain a notification channel that you want to use, then you can update the configured notification channels by using the following process:

  1. In the notification dialog, click Manage Notification Channels. You're taken to the Notification channels window in a new browser tab.
  2. To add a new notification channel, locate the channel type, click Add new, and then follow the channel-specific instructions contained in the previous table.
  3. Return to the original tab, and in the notification dialog, click Refresh .

    Notification dialog displaying the refresh and manage channels buttons.

  4. Select the notification channel from the updated list.

Editing and deleting channels

To edit or delete a notification channel by using the Cloud Console, do the following:

  1. In the Cloud Console, select Monitoring, or click the following button:

    Go to Monitoring

  2. In the Monitoring navigation pane, click Alerting.

  3. Click Edit notification channels.

    The Notification channels dashboard contains a section for each type of notification channel. Each section lists all configurations for that type:

    • To modify an entry, click Edit . Click Save after your changes are complete.
    • To delete an entry, click Delete . Click Delete in the confirmation dialog.

Adding the Monitoring app to a Slack channel

If you created Slack notification channels between November 21 and December 3, 2020, then your channels aren't receiving notifications. To resolve this issue, you must add the Monitoring app to your channels, as described in this section.

To configure a channel in a new Slack workspace, see setting up a new Slack channel.

To update an existing Slack channel to include Cloud Monitoring, do the following:

  1. Go to the Slack channel that you want to update.

  2. Invite the Monitoring app to the channel by sending the following message in the channel:

    /invite @Google Cloud Monitoring

    Be sure you invite the Monitoring app to the channel you specified when creating the notification channel in Monitoring.