En este documento, se describe cómo crear y administrar canales de notificación con bibliotecas cliente o con Google Cloud CLI, que invocan la API de Cloud Monitoring. Cloud Monitoring usa canales de notificaciones para notificarte a ti o a tu equipo de guardia cuando se cumple la condición de una política de alertas. Hay varios tipos de canales disponibles. Cada tipo se explica en un descriptor de canal de notificación. Un canal de notificación de un cierto tipo es una instancia del descriptor de ese tipo. Tus políticas de alertas incluyen referencias a los canales de notificación que se usan como vías de notificación.
Para que un canal de notificación pueda ser utilizado en una política de alertas, primero debe existir. Ya se te proporcionan los descriptores de canales de notificaciones, pero debes crear los canales para poder usarlos.
Para configurar canales de notificaciones con la consola de Google Cloud, consulta Cómo crear y administrar canales de notificaciones.
Las muestras de código que se usan en este documento se tomaron del ejemplo de la API de políticas de alertas, que se describe en Ejemplo: Copia de seguridad y restablecimiento.
Información acerca de la API
El recurso NotificationChannel
admite operaciones que te permiten administrar tus canales de notificaciones. También admite operaciones relacionadas con la administración del campo verificationStatus
de un canal:
- Enviar un código de verificación
- Generar un código para copiar el estado de verificación de un canal verificado en otros canales idénticos en el mismo proyecto o en uno nuevo
- Verificar el canal mediante el código creado en las dos operaciones anteriores
Para obtener más información, consulta los documentos de referencia de notificationChannels
.
Antes de comenzar
Para obtener los permisos que necesitas para ver y configurar canales de notificación con la API de Cloud Monitoring,
pídele a tu administrador que te otorgue el rol de IAM de
editor de NotificationChannel de Monitoring (roles/monitoring.notificationChannelEditor
) en tu proyecto.
Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.
También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.
Para obtener más información sobre los roles de Cloud Monitoring, consulta Controla el acceso con Identity and Access Management.
Enumera los tipos de canales de notificaciones
Monitoring proporciona varios tipos de canales de notificaciones integrados. Cada uno de estos tipos se describe en un NotificationChannelDescriptor
.
Estos descriptores tienen un campo type
, y el valor de este campo actúa como su identificador cuando se crean instancias de ese tipo de canal. Para recuperar una lista de los tipos de canales que puedes crear con la API de Cloud Monitoring o Google Cloud CLI, ingresa el siguiente comando:
$ gcloud beta monitoring channel-descriptors list --format='value(type)'
campfire
email
google_chat
hipchat
pagerduty
pubsub
slack
sms
webhook_basicauth
webhook_tokenauth
Para obtener más información sobre los canales de notificaciones, consulta Cómo crear y administrar canales de notificaciones.
Si tu canal de notificaciones preferido no es compatible, considera crear una canalización que se base en el envío de tus notificaciones a Pub/Sub. Para ver un ejemplo de Python que usa Flask, consulta Crea notificaciones personalizadas con Cloud Monitoring y Cloud Run. Para ver otros ejemplos, consulta el repositorio de Git cloud-alerting-notification-forwarding.
Para recuperar todos los descriptores de canales de un proyecto de Google Cloud, usa el método notificationChannelDescriptors.list
.
Los descriptores recuperados son de solo lectura.
Si buscas un descriptor específico y sabes su nombre, puedes usar el método notificationChannelDescriptors.get
para recuperar solo ese descriptor. El nombre de un descriptor de canal debe tener el formato projects/[PROJECT_ID]/notificationChannelDescriptors/[CHANNEL_TYPE]
[CHANNEL_TYPE]
, como uno de los tipos que se mencionan antes, por ejemplo:
projects/[PROJECT_ID]/notificationChannelDescriptors/email
gcloud
Para mostrar la lista de todos los descriptores de canales de notificaciones en un proyecto de Google Cloud, usa el comando gcloud beta monitoring channel-descriptors list
:
gcloud beta monitoring channel-descriptors list
Si se ejecuta de forma correcta, el comando list
proporciona una lista de todos los descriptores de canales en el proyecto especificado. Por ejemplo, el descriptor de canal email
aparece en la lista de la siguiente manera:
--- 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 ---
Todos los descriptores de canales incluyen estos campos:
name
: El nombre de recurso completamente calificado del descriptor de canalestype
: La parte del nombre que indica el tipo de canaldisplayName
: Una descripción del campotype
. Se usa para fines de visualización.description
: Una descripción breve del canal.labels
: Un conjunto de campos específicos para un tipo de canal. Cada tipo de canal tiene su propio conjunto de etiquetas.
Cuando se crea un canal, también obtiene un campo enabled
, con el valor true
de forma predeterminada.
Para mostrar un descriptor de un solo canal, usa gcloud beta monitoring
channel-descriptors describe
y especifica el nombre del descriptor. No es necesario que especifique el nombre completo. Por ejemplo, ambos comandos muestran la lista anterior:
gcloud beta monitoring channel-descriptors describe email
gcloud beta monitoring channel-descriptors describe projects/[PROJECT_ID]/notificationChannelDescriptors/email
Consulta las referencias gcloud beta monitoring channel-descriptors
list
y describe
para obtener más información. El comando describe
corresponde al método notificationChannelDescriptors.get
en la API.
Crea un canal de notificaciones
Puedes crear canales de notificación para tus proyectos de Google Cloud a partir de archivos JSON o YAML con Google Cloud CLI, y puedes crearlos de manera programática.
Para crear un canal de notificación, debes completar los valores de los campos de su descriptor. La mayoría, como type
, son comunes en todos los descriptores de canales de notificaciones; consulta notificationChannelDescriptors
.
Cada descriptor posee, además, un conjunto de etiquetas que varía de un descriptor a otro. Para ver el conjunto de etiquetas de un descriptor en particular, recupera el descriptor con el comando gcloud beta monitoring channel-descriptors describe
que se describe en Cómo enumerar los tipos de canales de notificación.
Por ejemplo, cuando se recupera el descriptor de canal email
, se muestra una sola etiqueta:
labels: - description: An address to send email. key: email_address
El descriptor de canal pubsub
también contiene una sola etiqueta que identifica el tema de Pub/Sub. Sin embargo, los canales pueden contener varias etiquetas. Por ejemplo, el descriptor de canal slack
tiene dos etiquetas:
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
Cuando se recupera el descriptor de canal webhook_basicauth
, se muestran varias etiquetas:
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
Ya sea que crees un canal nuevo de manera programática o desde la línea de comandos, el valor de type
en tu especificación debe coincidir con el campo type
en el descriptor de canal de notificaciones correspondiente. Las claves de etiquetas necesarias también deben coincidir con las del descriptor de canal.
Algunas etiquetas corresponden a las credenciales que se usan para autenticarse con el proveedor. Cuando se crea un canal, los valores para estas etiquetas deben obtenerse del proveedor. Obtener una credencial puede implicar el uso de una página para generar claves de API en el sitio web del proveedor o completar un flujo de acceso de OAuth con el proveedor. Los detalles específicos para obtener esa credencial dependen de cada proveedor.
Por ejemplo, a continuación se muestra la especificación de un nuevo canal de notificaciones pubsub
en JSON:
{ "type": "pubsub", "displayName": "Notifications", "description": "Pub/Sub channel for notifications", "labels": { "topic": "projects/[PROJECT_ID]/topics/notificationTopic" }, }
El valor type
(pubsub
) y la clave de una sola etiqueta (topic
) coinciden con los campos type
y labels.key
en el descriptor de canal correspondiente.
Los canales están habilitados de manera predeterminada. Si deseas crear un canal inactivo, puedes incluir el campo enabled
con el valor false
.
Los siguientes ejemplos ilustran la creación de los canales de notificación.
gcloud
Para crear un canal de notificaciones en un proyecto de Google Cloud, usa el comando gcloud beta monitoring
channels create
. Si deseas cargar el canal desde un archivo, usa la marca --channel-content-from-file
para especificarlo.
Con el siguiente ejemplo, se crea un nuevo canal de Pub/Sub desde el archivo pubsub-channel.json
:
gcloud beta monitoring channels create --channel-content-from-file="pubsub-channel.json"
Si funciona, este comando muestra el nombre del canal nuevo, por ejemplo:
Created notification channel [projects/[PROJECT_ID]/notificationChannels/1355376463305411567].
Consulta la referencia de gcloud beta monitoring channels create
para obtener más información.
C#
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Go
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Java
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
PHP
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Ejemplo: Crea un canal de notificaciones de Slack
Para configurar un canal de notificaciones para una app de Slack, haz lo siguiente:
Configura tu app de Slack:
- Si aún no tienes una app de Slack, sigue la documentación de referencia de Slack para crear una y, luego, instálala en tu lugar de trabajo.
- Configura tu app de Slack con los permisos de OAuth para
chat:write
ychat:write.public
. - Copia el token de OAuth del usuario bot de la app.
Crea un archivo que defina la configuración de tu canal de notificaciones. Incluye una etiqueta en la que la clave
auth_token
tenga el valor del token de OAuth del usuario bot de tu app de Slack. Por ejemplo:{ "description": "A Slack notification channel", "displayName": "Slack", "type": "slack", "enabled": true, "labels": { "auth_token": "OAUTH_TOKEN_VALUE", "channel_name": "SLACK_CHANNEL_NAME" } }
Ejecuta el siguiente comando para crear el canal de notificaciones:
gcloud beta monitoring channels create --channel-content-from-file="FILE_NAME"
Enumera los canales de notificaciones de un proyecto
Para recuperar todos los canales de notificaciones de un proyecto de Google Cloud, usa el método notificationChannels.list
. Este método también admite opciones filter
y orderBy
para restringir y ordenar los resultados; consulta Ordena y filtra.
Si buscas un canal específico y sabes su nombre, puedes usar el método notificationChannels.get
para recuperar solo ese canal. El nombre de un canal tiene el formato projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID]
, por ejemplo:
projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Cuando recuperas un canal, los valores sensibles, como los tokens de autenticación y las claves de API, pueden ofuscarse por motivos de seguridad. Si copias un canal existente para crear uno nuevo, debes corregir los valores ofuscados.
gcloud
Para enumerar todos los canales de notificaciones en un proyecto de Google Cloud, usa el comando gcloud beta monitoring channels list
:
gcloud beta monitoring channels list
Si se ejecuta de forma correcta, el comando list
proporciona una lista de todos los canales del proyecto especificado. Por ejemplo, puede que el comando anterior muestre una lista que incluye las siguientes entradas:
--- 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
Para mostrar un solo canal, usa gcloud beta monitoring
channels describe
y especifica el nombre del canal.
Por ejemplo, este comando muestra el canal de Pub/Sub que se muestra en la lista anterior:
gcloud beta monitoring channels describe projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Consulta las referencias gcloud beta monitoring channels list
y describe
para obtener más información. El comando describe
corresponde al método notificationChannels.get
en la API.
C#
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Go
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Java
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
PHP
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Cómo borrar un canal de notificaciones de un proyecto
Para borrar un canal de notificaciones de un proyecto de Google Cloud, usa el método notificationChannels.delete
y proporciona el nombre del canal de notificaciones que deseas borrar. El nombre de un canal es el valor del campo name
, no de displayName
, en la instancia NotificationChannel
.
El nombre de un canal tiene el formato projects/[PROJECT_ID]/notificationChannels/[CHANNEL_ID]
, por ejemplo:
projects/[PROJECT_ID]/notificationChannels/1355376463305411567
De forma predeterminada, si intentas borrar un canal al que hace referencia una política de alertas, este no se borrará. Para forzar la eliminación de las referencias de las políticas de alertas y borrar el canal, establece la opción force
en true
. Esta opción quita automáticamente el canal de todas las políticas de referencia.
gcloud
Para borrar un canal de notificaciones, usa gcloud beta monitoring channels
delete
y especifica el nombre del canal que deseas borrar. Por ejemplo, con el siguiente comando, se borra el canal email
, que se creó en otro ejemplo:
gcloud beta monitoring channels delete projects/[PROJECT_ID]/notificationChannels/1355376463305411567
Consulta la referencia de gcloud beta monitoring channels delete
para obtener más información.
C#
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Go
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Java
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
PHP
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Modifica un canal de notificaciones
Para modificar un canal de notificaciones, usa el método notificationChannels.patch
(en la API de REST).
Otras implementaciones de la API y Google Cloud CLI llaman a esto update
en lugar de patch
.
Una operación de actualización puede reemplazar el canal existente por completo o puede modificar un subconjunto de campos. Por ejemplo, puedes habilitar o inhabilitar el canal. La inhabilitación de un canal impide la entrega de notificaciones al canal. Si se pretende que el cambio sea temporal, por lo general, es más conveniente inhabilitar un canal que eliminarlo de las políticas de alertas que hacen referencia a él.
gcloud
Para habilitar un canal de notificaciones que esté inhabilitado, usa el comando gcloud beta monitoring channels update
y proporciona la marca --enabled
. Con el siguiente comando, se habilita el canal de notificaciones email
que se creó, en el estado inhabilitado, en un ejemplo anterior:
gcloud beta monitoring channels update projects/[PROJECT_ID]/notificationChannels/1355376463305411567 --enabled
Para inhabilitar una política, usa el mismo comando y proporciona la marca --no-enabled
.
Consulta la referencia de gcloud beta monitoring channels update
para obtener más información. El comando update
corresponde al método notificationChannels.patch
en la API de REST.
C#
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Go
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Node.js
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Java
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
PHP
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Python
Para autenticarte en Monitoring, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Cómo ver los registros del canal de notificaciones
Puedes usar el Explorador de registros para ver los errores del canal de notificaciones:
-
En la consola de Google Cloud, ve a la página Explorador de registros.
Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.
Ingresa y ejecuta tu consulta. Para consultas específicas sobre errores de canales de notificación, consulta Consultas de Cloud Monitoring.