En esta página, se describe cómo puedes configurar la documentación de tu política de alertas. para que las notificaciones brinden a los responsables de la respuesta ante incidentes recursos y información adicional para la resolución de incidentes.
Estructura de la documentación
La documentación de una política de alertas consta de un asunto, contenido y vínculos. Puedes configurar la documentación en la consola de Google Cloud, la API de Cloud Monitoring y la Google Cloud CLI.
Sujetos
El asunto de tu documentación aparece en el asunto de las notificaciones de incidentes relacionados con tu política de alertas. Los destinatarios de las notificaciones pueden administrarlas y ordenarlas por asunto.
Los asuntos tienen un límite de 255 caracteres. Si no defines un sujeto en tu documentación y, luego, Cloud Monitoring determina el asunto. Las líneas de asunto admiten texto sin formato y variables.
API de Cloud Monitoring
Para configurar el asunto de la notificación, usa el campo subject
de la política de alertas documentation
.
Consola de Google Cloud
Para configurar el asunto de la notificación, usa el campo Asunto de la notificación en la sección Notificaciones y nombre de la página Crear política de alertas.
Contenido
El contenido de tu documentación aparece en los siguientes tipos de notificaciones:
- Correo electrónico, debajo del encabezado Documentación sobre políticas
- PagerDuty
- Pub/Sub
- Slack
- Webhooks
Te recomendamos que configures tu contenido para que los equipos de respuesta a incidentes puedan ver los pasos de solución y la información del incidente en las notificaciones relacionadas con tu política de alertas. Por ejemplo, puedes configurar el documentación para incluir un resumen del incidente y información sobre recursos relevantes.
El contenido de la documentación admite texto sin formato, Markdown, variables y controles específicos de canal.
API de Cloud Monitoring
Para configurar el contenido de la documentación, usa el campo content
de la política de alertas documentation
.
Consola de Google Cloud
Para configurar el contenido de la documentación, usa el campo Documentación en la sección Notificaciones y nombre de la página Crear política de alertas.
Vínculos
Puedes agregar vínculos a tu documentación para que los responsables de la respuesta ante incidentes puedan acceder a recursos como guías, repositorios y paneles de Google Cloud desde una notificación.
API de Cloud Monitoring
Los vínculos de documentación configurados en la API de Cloud Monitoring aparecen en los siguientes tipos de notificaciones:
- Correo electrónico, en el encabezado Vínculos rápidos
- PagerDuty
- Pub/Sub
- Webhooks
Para configurar un vínculo, agrega un Link
a la
documentation
de tu política de alertas.
Cada vínculo se representa con un display_name
y un url
. Puedes tener hasta
tres vínculos en tu documentación.
La siguiente configuración usa links
con una URL
para crear un vínculo a una guía de incidentes. La URL incluye una variable para que los destinatarios de las notificaciones puedan acceder al playbook correcto según el recurso supervisado en el que ocurrió el incidente:
"links" [
{
"displayName": "Playbook",
"url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
}
]
Consola de Google Cloud
Los vínculos de documentación configurados en la consola de Google Cloud aparecen con el resto del contenido de la documentación en los siguientes tipos de notificaciones:
- Correo electrónico, en el encabezado Documentación de políticas
- PagerDuty
- Pub/Sub
- Slack
- Webhooks
Puedes agregar vínculos al contenido de tu documentación incluyéndolos en el campo Documentación de tu política de alertas. Por ejemplo, en la siguiente documentación, se enumera una URL para una guía de cliente:
### Troubleshooting and Debug References Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}
Markdown en el contenido de la documentación
Puedes usar Markdown para dar formato al contenido de tu documentación. El contenido de la documentación admite el siguiente subconjunto de etiquetas de Markdown:
- Encabezados, indicados por caracteres de hash iniciales.
- Listas sin ordenar, que los caracteres iniciales, menos o asteriscos indican.
- Listas ordenadas, que un número inicial seguido de un punto indica.
- Texto en cursiva, que un guion bajo o asteriscos alrededor de una frase indica.
- Texto en negrita, que el doble guion bajo o asteriscos alrededor de una frase indica.
- Vínculos, que la sintaxis
[link text](url)
indica. Sin embargo, recomendamos usarLink
para configurar vínculos a tu contenido.
Para obtener más información sobre este etiquetado, consulta cualquier referencia de Markdown, por ejemplo, Guía de Markdown.
Variables en la documentación
Para personalizar el texto de tu documentación, puedes usar variables
con el formato ${varname}
. Cuando el documento se envía con una notificación, la cadena ${varname}
se reemplaza por un valor extraído del recurso de Google Cloud correspondiente, como se describe en la siguiente tabla.
Variable | Valor |
---|---|
condition.name |
El nombre del recurso de REST de la condición, comoprojects/foo/alertPolicies/1234/conditions/5678 |
condition.display_name |
El nombre visible de una condición, como CPU usage increasing rapidly . |
log.extracted_label.KEY |
El valor de la etiqueta KEY , extraído
de una entrada de registro. Solo para políticas de alertas basadas en registros. Para obtener más información, consulta Crea una política de alertas basada en registros con la API de Monitoring. |
metadata.system_label.KEY |
El valor de la etiqueta de metadatos de recursos proporcionada por el sistema KEY .1 |
metadata.user_label.KEY |
El valor de la etiqueta de metadatos de recursos definida por el usuario KEY .1,3 |
metric.type |
El tipo de métrica, comocompute.googleapis.com/instance/cpu/utilization |
metric.display_name |
El nombre visible del tipo de métrica, como CPU utilization . |
metric.label.KEY |
El valor de la etiqueta de métrica Cuando el valor de la variable Cuando migra una regla de alertas de Prometheus, las plantillas del campo de alerta de Prometheus También puedes usar |
metric_or_resource.labels |
Esta variable renderiza todos los valores de etiquetas de métricas y recursos como una lista ordenada de pares Cuando migras una regla de alerta de Prometheus, las plantillas de campos de alerta de Prometheus |
metric_or_resource.label.KEY |
Cuando migra una regla de alertas de Prometheus, las plantillas del campo de alerta de Prometheus |
policy.name |
El nombre del recurso REST de la política, como projects/foo/alertPolicies/1234 . |
policy.display_name |
El nombre visible de una política, como High CPU rate of change . |
policy.user_label.KEY |
El valor de la etiqueta de usuario KEY .1
Las claves deben comenzar con una letra minúscula. Las claves y los valores pueden contener solo letras minúsculas, dígitos, guiones bajos y guiones. |
project |
El ID del proyecto de alcance de un permiso de métricas, como a-gcp-project . |
resource.type |
El tipo de recurso supervisado, como gce_instance |
resource.project |
El ID del proyecto del recurso supervisado de la política de alertas |
resource.label.KEY |
El valor de la etiqueta de recurso
KEY .1,2,3Para encontrar las etiquetas asociadas con el tipo de recurso supervisado, consulta Lista de recursos. |
1 Por ejemplo, ${resource.label.zone}
se reemplaza por el valor de la etiqueta zone
. Los valores de estas variables están sujetos a la agrupación; consulta valores null
para obtener más información.
2 Para recuperar el valor de la etiqueta project_id
en un recurso supervisado en la política de alertas, usa ${resource.project}
.
3 No puedes acceder a etiquetas de metadatos de recursos definidas por el usuario mediante
usando resource.label.KEY.
Usa metadata.user_label.KEY
en su lugar.
Notas de uso
- Solo se admiten las variables en la tabla. No puedes combinarlos en
expresiones más complejas, como
${varname1 + varname2}
. - Para incluir la string literal
${
en tu documentación, escapa el símbolo$
con un segundo símbolo$
;$${
se procesará como${
en tu documentación. - Estas variables se reemplazan por sus valores solo en las notificaciones enviadas a través de canales de notificación. En la consola de Google Cloud, cuando de la documentación, ves las variables, no los valores. En los ejemplos de la consola, se incluyen descripciones de incidentes y la vista previa de la documentación cuando se crea una política de alertas.
- Asegúrate de que la configuración de agregación de la condición no elimine la
etiqueta. Si se elimina la etiqueta, el valor de la etiqueta en la notificación es
null
. Para obtener más información, consulta La variable para una etiqueta de métrica es nula.
null
valores
Los valores de las variables metric.*
, resource.*
y metadata.*
derivan de series temporales. Sus valores pueden ser null
si no se muestran valores de la consulta de series temporales.
Las variables
resource.label.KEY
ymetric.label.KEY
pueden tener Valoresnull
si tu política de alertas usa agregación de series cruzadas (reducción), por ejemplo, calcular la SUMA en cada uno de los series temporales que coinciden con un filtro. Cuando se usa la agregación de series cruzadas, las etiquetas no usadas en la agrupación se descartan y, como resultado, se renderizan comonull
cuando la variable se reemplaza por su valor. Todas las etiquetas se conservan cuando no hay agregación entre series. Para obtener más información, consulta La variable de una etiqueta de métrica es nula.Los valores para las variables
metadata.*
están disponibles solo si las etiquetas se incluyen explícitamente en el filtro o la agrupación de una condición a fin de realizar la agregación de series cruzadas. Es decir, debes consultar la etiqueta de metadatos en el filtro o la agrupación para que tenga un valor para la plantilla.
Resolución variable
Las variables en las plantillas de documentación solo se resuelven en las notificaciones que se envían con los siguientes canales de notificación:
- Correo electrónico
- Google Chat
- Slack
- Pub/Sub, esquema JSON versión 1.2
- Webhooks, versión 1.2 del esquema JSON
- PagerDuty, versión 1.2 del esquema JSON
Controles del canal
El texto en el campo de documentación también puede incluir caracteres especiales que usa el propio canal de notificación para controlar el formato y las notificaciones.
Por ejemplo, Slack usa @
para las menciones. Puedes usar @
para vincular la notification a un ID de usuario específico. Las menciones no pueden incluir nombres.
Supongamos que incluyes una cadena como esta en el campo de documentación:
<@backendoncall> Incident created based on policy ${policy.display_name}
Cuando el canal de Slack relevante recibe el campo de documentación como parte
de la notificación, la cadena anterior hace que Slack envíe
mensaje adicional al ID de usuario
backendoncall
El mensaje que Slack le envía al usuario
puedan contener información relevante de la notificación; por ejemplo,
“Incidente creado según la política Alta tasa de cambio de CPU”.
Estas opciones adicionales son específicas de los canales. Para obtener más información sobre lo que podría estar disponible, consulta la documentación que proporciona el proveedor del canal.
Ejemplo
El siguiente ejemplo muestra las versiones de la consola de Google Cloud y la API de Cloud Monitoring de documentación de plantillas para una política de alertas de uso de CPU. En estos ejemplos, se usa un correo electrónico para el tipo de canal de notificaciones. Las plantillas de documentación incluyen varias variables para resumir el incidente y hacer referencia a la política de alertas y a los recursos REST de condiciones.
API de Cloud Monitoring
"documentation": {
"content": "### CPU utilization exceeded\n\n### Summary\n\nThe ${metric.display_name} of the ${resource.type} ${resource.label.instance_id} in the project ${resource.project} has exceeded 5% for over 60 seconds.\n\n#### Additional resource information\n\nCondition resource name: ${condition.name} \nAlerting policy resource name: ${policy.name}",
"mimeType": "text/markdown",
"subject": "Alert: ${metric.display_name} exceeded",
"links": [
{
"displayName": "Playbook",
"url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
},
{
"displayName": "Repository with debug scripts",
"url": "https://altostrat.com"
},
{
"displayName": "Google Cloud dashboard",
"url": "https://example.com"
}
]
}
En la siguiente imagen, se muestra cómo aparece esta plantilla en una notificación por correo electrónico:
Consola de Google Cloud
### CPU utilization exceeded #### Summary The ${metric.display_name} of the ${resource.type} ${resource.label.instance_id} in the project ${resource.project} has exceeded 5% for over 60 seconds. #### Additional resource information Condition resource name: ${condition.name} Alerting policy resource name: ${policy.name} #### Troubleshooting and Debug References Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type} Repository with debug scripts: https://altostrat.com ${resource.type} dashboard: https://example.com
La siguiente imagen muestra cómo aparece esta plantilla en un correo electrónico notificación: