This document describes how to create and manage notification channels by using client libraries or by using the Google Cloud CLI, both of which invoke the Cloud Monitoring API. Cloud Monitoring uses notification channels to notify you, or your on-call team, when the condition of an alerting policy is met. There are several available channel types; each type is described in a notification-channel descriptor. A notification channel of a certain type is an instance of that type's descriptor. Your alerting policies include references to the notification channels to use as notification pathways.
A notification channel must exist before it can be used in an alerting policy. The notification-channel descriptors are provided to you, but you have to create the channels before they can be used.
To configure notification channels by using the Google Cloud console, see Create and manage notification channels.
The code samples used in this document are extracted from the alerting-policy API example, described in Example: backup and restore.
About the API
The NotificationChannel
resource supports operations that let you
manage your notification channels. It also supports operations related to
managing the verificationStatus
field of a channel:
- Sending a verification code
- Generating a code for copying the verification status of a verified channel to other identical channels in the same or a new project
- Verifying the channel using the code created by the previous two operations
For more information, see the notificationChannels
reference
documents.
Before you begin
To get the permissions that you need to view and configure notification channels by using the Cloud Monitoring API,
ask your administrator to grant you the
Monitoring NotificationChannel Editor (roles/monitoring.notificationChannelEditor
) IAM role on your project.
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
For more information about Cloud Monitoring roles, see Control access with Identity and Access Management.
List the types of notification channels
Monitoring provides a number of built-in notification-channel
types. Each of
these types is described in a NotificationChannelDescriptor
.
These descriptors have a type
field, and the value of this field
acts as an identifier for it when creating instances of that
channel type. To retrieve a list of channel types that you can create with the
Cloud Monitoring API or the Google Cloud CLI, enter the following command:
$ gcloud beta monitoring channel-descriptors list --format='value(type)'
campfire
email
google_chat
hipchat
pagerduty
pubsub
slack
sms
webhook_basicauth
webhook_tokenauth
For more information about notification channels, see Create and manage notification channels.
If your preferred notification channel isn't supported, consider creating a pipeline that relies on sending your notifications to Pub/Sub. For a Python example that uses Flask, see Creating custom notifications with Cloud Monitoring and Cloud Run. For other examples, see the cloud-alerting-notification-forwarding Git repository.
To retrieve all the channel descriptors in a Google Cloud project, use the
notificationChannelDescriptors.list
method.
The retrieved descriptors are read-only.
If you are looking for a specific descriptor and you know its name,
you can use the notificationChannelDescriptors.get
method
to retrieve only that channel descriptor. The name of a channel
descriptor has the format
projects/[PROJECT_ID]/notificationChannelDescriptors/[CHANNEL_TYPE]
[CHANNEL_TYPE]
must be one of the types listed above, for example:
projects/[PROJECT_ID]/notificationChannelDescriptors/email
gcloud
To list all the notification-channel descriptors in a Google Cloud project,
use the gcloud beta monitoring channel-descriptors list
command:
gcloud beta monitoring channel-descriptors list
If successful, the list
command provides a listing of all the channel
descriptors in the specified project. For example, the email
channel
descriptor appears in the list like this:
--- description: A channel that sends notifications via email. displayName: Email labels: - description: An address to send email. key: email_address name: projects/[PROJECT_ID]/notificationChannelDescriptors/email type: email ---
All channel descriptors include these fields:
name
: The fully qualified resource name of the channel descriptortype
: The part of the name that indicates the type of channeldisplayName
: A description of thetype
field, for display purposesdescription
: A brief description of the channellabels
: A set of fields specific to a channel type. Each channel type has its own set of labels.
When a channel is created, it also gets an enabled
field, with the value
true
by default.
To list a single channel descriptor, use gcloud beta monitoring
channel-descriptors describe
, instead, and specify the name of the channel
descriptor. You don't need to specify the fully qualified name. For example,
both of these commands return the listing above:
gcloud beta monitoring channel-descriptors describe email
gcloud beta monitoring channel-descriptors describe projects/[PROJECT_ID]/notificationChannelDescriptors/email
See the gcloud beta monitoring channel-descriptors
list
and describe
references for more information. The describe
command corresponds to the
notificationChannelDescriptors.get
method in the API.
Create a notification channel
You can create notification channels for your Google Cloud projects from JSON or YAML files by using the Google Cloud CLI, and you can create them programmatically.
To create a notification channel, you must supply values for the
fields in its descriptor. Most of these, like type
, are common
across all notification-channel descriptors; see
notificationChannelDescriptors
.
Each descriptor also has a set of labels, and this set varies across the
descriptors. To see the set of labels for a particular descriptor, retrieve
the descriptor using the gcloud beta monitoring channel-descriptors describe
command described in List the types of notification channels.
For example, retrieving the
email
channel descriptor shows a single label:
labels: - description: An address to send email. key: email_address
The pubsub
channel descriptor also contains a single label; that label
identifies the Pub/Sub topic. However, channels can contain multiple
labels. For example, the slack
channel descriptor has two labels:
labels: - description: A permanent authentication token provided by Slack. This field is obfuscated by returning only a few characters of the key when fetched. key: auth_token - description: The Slack channel to which to post notifications. key: channel_name
Retrieving the webhook_basicauth
channel descriptor shows several labels:
labels: - description: The password. The field is obfuscated when the channel is fetched. key: password - description: The public URL to which to publish the webhook. key: url - description: The username. key: username
Whether you create a new channel programmatically or from the command line,
the value of the type
in your specification must match the type
field in
the corresponding notification-channel descriptor. Any required label
keys must also match those in the channel descriptor.
Some labels correspond to credentials used to authenticate with the provider. When creating a channel, the values for these labels must be obtained from the provider. Obtaining a credential might involve using an API key-generation page on the provider's website or completing an OAuth login flow with the provider. The specifics of how to obtain such a credential depend on the particular provider.
For example, the following shows the specification of a new pubsub
notification channel in JSON:
{ "type": "pubsub", "displayName": "Notifications", "description": "Pub/Sub channel for notifications", "labels": { "topic": "projects/[PROJECT_ID]/topics/notificationTopic" }, }
The type
value (pubsub
) and the single label key (topic
)
match the type
and labels.key
fields in the corresponding channel
descriptor.
Channels are enabled by default. If you want to create an inactive channel,
you can include the field enabled
with the value false
.
The following examples illustrate the creation of notification channels.
gcloud
To create a notification channel in a Google Cloud project, use the gcloud beta monitoring
channels create
command. To load the channel from a file, use the
--channel-content-from-file
flag to specify the file.
The following example creates a new Pub/Sub channel
from the pubsub-channel.json
file:
gcloud beta monitoring channels create --channel-content-from-file="pubsub-channel.json"
If successful, this command returns the name of the new channel, for example:
Created notification channel [projects/[PROJECT_ID]/notificationChannels/1355376463305411567].
See the gcloud beta monitoring channels create
reference for more information.
C#
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Example: Create a Slack notification channel
To configure a notification channel for a Slack app, do the following:
Configure your Slack app:
- If you don't already have a Slack app, follow the Slack reference documentation to create one and install it to your workspace.
- Configure your Slack app with OAuth scopes for
chat:write
andchat:write.public
. - Copy the app's Bot User OAuth token.
Create a file that defines the configuration of your notification channel. Include a label where the
auth_token
key has the value of your Slack app's Bot User OAuth token. For example:{ "description": "A Slack notification channel", "displayName": "Slack", "type": "slack", "enabled": true, "labels": { "auth_token": "OAUTH_TOKEN_VALUE", "channel_name": "SLACK_CHANNEL_NAME" } }
Run the following command to create the notification channel:
gcloud beta monitoring channels create --channel-content-from-file="FILE_NAME"
List notification channels in a project
To retrieve all the notification channels in a Google Cloud project, use the
notificationChannels.list
method. This method also supports
filter
and orderBy
options to restrict and sort the results;
see Sorting and Filtering.
If you are looking for a specific channel and you know its name,
you can use the notificationChannels.get
method
to retrieve only that channel. The name of a channel has the format
projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID]
, for example:
projects/[PROJECT_ID]/notificationChannels/1355376463305411567
When you retrieve a channel, sensitive values like authentication tokens and API keys might be obfuscated for security reasons. If you are creating a new channel by copying an existing one, any obfuscated values need to be corrected.
gcloud
To list all the notification channels in a Google Cloud project, use the
gcloud beta monitoring channels list
command:
gcloud beta monitoring channels list
If successful, the list
command provides a listing of all the channels
in the specified project. For example, the command above might return a list
that includes the following entries:
--- description: E-mail channel created by gcloud as a test displayName: test e-mail channel enabled: false labels: email_address: user@example.com name: projects/[PROJECT_ID]/notificationChannels/1355376463305411567 type: email --- description: Pub/Sub channel for notifications displayName: Notifications enabled: true labels: topic: projects/[PROJECT_ID]/topics/notificationTopic name: projects/[PROJECT_ID]/notificationChannels/1355376463305411567 type: pubsub
To list a single channel, use gcloud beta monitoring
channels describe
, instead, and specify the name of the channel.
For example, this command returns the Pub/Sub channel shown in the
listing above:
gcloud beta monitoring channels describe projects/[PROJECT_ID]/notificationChannels/1355376463305411567
See the gcloud beta monitoring channels list
and describe
references for more information. The describe
command corresponds to the
notificationChannels.get
method in the API.
C#
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Delete a notification channel from a project
To delete a notification channel from a Google Cloud project, use the
notificationChannels.delete
method, and supply the name
of the notification channel to delete. The name of a channel is the value of
the name
field, not the displayName
, in the NotificationChannel
instance.
The name of a channel has the format
projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID]
, for example:
projects/[PROJECT_ID]/notificationChannels/1355376463305411567
By default, if you attempt to delete a channel that is referenced by an
alerting policy, then the channel won't be deleted. To force the removal of
references from alerting policies and delete the channel, set the force
option to true
. This option automatically removes the channel from all
referencing policies.
gcloud
To delete a notification channel, use gcloud beta monitoring channels
delete
, and specify the name of the channel to delete. For example, the
following command deletes the email
channel created in another example:
gcloud beta monitoring channels delete projects/[PROJECT_ID]/notificationChannels/1355376463305411567
See the
gcloud beta monitoring channels delete
reference for more information.
C#
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Modify a notification channel
To modify a notification channel, use the
notificationChannels.patch
method (in the REST API).
Other API implementations and the Google Cloud CLI call this update
instead of patch
.
An update operation can wholly replace the existing channel, or it can modify a subset of fields. For example, you can enable and disable the channel. Disabling a channel prevents delivery of notifications to the channel. Disabling a channel is typically more convenient than removing the channel from the alerting policies that refer to it, if the change is intended to be temporary.
gcloud
To enable a notification channel that is disabled, use the
gcloud beta monitoring channels update
command, and provide the --enabled
flag. The following command enables the email
notification channel
created—in the disabled state—in a previous example:
gcloud beta monitoring channels update projects/[PROJECT_ID]/notificationChannels/1355376463305411567 --enabled
To disable a policy, use the same command and provide the --no-enabled
flag.
See the gcloud beta monitoring channels update
reference for more information. The update
command corresponds to the
notificationChannels.patch
method in the REST API.
C#
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To authenticate to Monitoring, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
View notification channel logs
You can use the Logs Explorer to view notification channel errors:
-
In the Google Cloud console, go to the Logs Explorer page:
If you use the search bar to find this page, then select the result whose subheading is Logging.
Enter and run your query. For queries specific to notification channel errors, see Cloud Monitoring queries.