Alerting policies typically have some way to let you know when they have been triggered. These “ways to let you know” are called notification channels. There are several available channel types; each is 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.
The code samples used here are extracted from the alerting-policy API example, described in Example: backup and restore.
Channel descriptors
Stackdriver 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. You can retrieve the available channel types, described more
generally in Notification options, with the following
command:
$ gcloud alpha monitoring channel-descriptors list --format='value(type)'
email
pagerduty
slack
sms
webhook_basicauth
webhook_tokenauth
To retrieve all the channel descriptors in a 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/a-gcp-project/notificationChannelDescriptors/email
gcloud command
To list all the notification-channel descriptors in a project, use the
gcloud alpha monitoring channel-descriptors list
command:
gcloud alpha 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/a-gcp-project/notificationChannelDescriptors/email
type: email
---
To list a single channel descriptor, use gcloud alpha monitoring
channel-descriptors describe
, instead, and specify the name of the channel
descriptor. For example, this command returns only the listing above:
gcloud alpha monitoring channel-descriptors describe projects/a-gcp-project/notificationChannelDescriptors/email
See the gcloud alpha monitoring channel-descriptors
list
and describe
references for more information. The describe
command corresponds to the
notificationChannelDescriptors.get
method in the API.
Notification channels
A notification channel is an instance of one of the notification-channel descriptors discussed in Channel descriptors.
The NotificationChannel
resource supports five operations:
- Creating new channels
- Deleting existing channels
- Retrieving specific channels
- Retrieving all channels
- Modifying existing channels
There are three other 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
See the notificationChannels
reference for
more information on them.
Creating channels
You can create notification channels from JSON or YAML files using the
gcloud
command-line utility, 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 alpha monitoring channel-descriptors describe
command described in Channel descriptors. For example, retrieving the
email
channel descriptor shows a single label:
labels:
- description: An address to send email.
key: email_address
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 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 email
notification
channel in JSON:
{
"type": "email",
"displayName": "test e-mail channel",
"description": "E-mail channel created by gcloud as a test",
"labels": {
"email_address": "user@example.com"
},
"enabled": false
}
The type
value (email
) and the single label key (email_address
)
match the type
and labels.key
fields in the corresponding channel
descriptor.
The following examples illustrate the creation of notification channels.
gcloud command
To create a notification channel in a project, use the gcloud alpha 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 e-mail channel in
a-gcp-project
from the new-email-channel.json
file:
gcloud alpha monitoring channels create --channel-content-from-file="new-email-channel.json"
If successful, this command returns the name of the new channel, for example:
Created notification channel [projects/a-gcp-project/notificationChannels/1355376463305411567].
See the gcloud alpha monitoring channels create
reference for more information.
C#
Node.js
Go
Java
PHP
Python
Retrieving channels
To retrieve all the notification channels in a 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/a-gcp-project/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 command
To list all the notification channels in a project, use the
gcloud alpha monitoring channels list
command:
gcloud alpha monitoring channels list
If successful, the list
command provides a listing of all the channels
in the specified project. For example, the command above results in a list
that includes the following:
---
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/a-gcp-project/notificationChannels/1355376463305411567
type: email
---
To list a single channel, use gcloud alpha monitoring
channels describe
, instead, and specify the name of the channel.
For example, this command returns only the listing above:
gcloud alpha monitoring channels describe projects/a-gcp-project/notificationChannels/1355376463305411567
See the gcloud alpha monitoring channels list
and describe
references for more information. The describe
command corresponds to the
notificationChannels.get
method in the API.
C#
Node.js
Go
Java
PHP
Python
Deleting channels
To delete a notification channel from a 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/a-gcp-project/notificationChannels/1355376463305411567
By default, if you attempt to delete a channel that is referenced by an
alerting policy, the channel will not be deleted. To force the removal of
references from alerting policies and delete the channel, set the force
option to true
.
gcloud command
To delete a notification channel, use gcloud alpha 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 alpha monitoring channels delete projects/a-gcp-project/notificationChannels/1355376463305411567
See the
gcloud alpha monitoring channels delete
reference for more information.
C#
Go
Java
PHP
Node.js
Python
Modifying channels
To modify a notification channel, use the
notificationChannels.patch
method (in the REST API).
Other API implementations and the gcloud
interface 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 command
To enable a notification channel that is disabled, use the
gcloud alpha 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 alpha monitoring channels update projects/a-gcp-project/notificationChannels/1355376463305411567 --enabled
To disable a policy, use the same command and provide the --no-enabled
flag.
See the gcloud alpha monitoring channels update
reference for more information. The update
command corresponds to the
notificationChannels.patch
method in the REST API.
C#
Go
Node.js
Java
PHP
Python