Anota alertas con documentación definida por el usuario

En esta página, se describe cómo puedes configurar la documentación de la política de alertas para personalizar el cuerpo y el asunto de tus notificaciones. Los campos de documentación admiten texto sin formato, Markdown, variables y controles específicos del canal.

Agrega información a la notificación

Puedes proporcionar a los responsables de la respuesta a las alertas información y pasos para solucionar el incidente en la notificación. Para ello, especifica ese contenido cuando creas la política de alertas. Por ejemplo, puedes configurar la política de alertas para incluir vínculos a una guía interna en cualquier notificación.

Para ver una implementación de muestra, consulta la sección Ejemplo de esta página.

Configura el asunto de las notificaciones

Puedes administrar y ordenar tus notificaciones si especificas su línea de asunto. Las líneas de asunto tienen un límite de 255 caracteres. Si no defines un asunto en tu documentación, entonces Cloud Monitoring lo determina.

Puedes configurar el asunto cuando usas la API de Cloud Monitoring, Google Cloud CLI o la consola de Google Cloud.

Para ver una implementación de muestra, consulta la sección Ejemplo de esta página.

Usa Markdown

El campo de documentación admite el siguiente subconjunto de etiquetado 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.

Para obtener más información sobre este etiquetado, consulta cualquier referencia de Markdown, por ejemplo, Guía de Markdown.

Usa variables

Para personalizar el texto en tu documentación, puedes usar variables con el formato ${varname}. Cuando la documentación se envía con una notificación, la string ${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, como
projects/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 las alertas basadas en registros. Si quieres obtener más información, consulta Crea una alerta basada en registros (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 definidos por el usuario KEY.1,3
metric.type El tipo de métrica, como
compute.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 KEY.1
Para encontrar las etiquetas asociadas con el tipo de métrica, consulta Lista de métricas.

Cuando el valor de la variable ${metric.label.KEY} no comienza con un dígito, una letra, una barra diagonal (/) ni un signo igual (=), Monitoring omite la etiqueta de las notificaciones.

Cuando migras una regla de alerta de Prometheus, las plantillas de campo de alerta de Prometheus {{$value}} y {{humanize $value}} aparecen como ${metric.label.VALUE} en la configuración de la documentación de la política de alertas. En este caso, VALUE contiene el valor de la consulta de PromQL.

También puedes usar ${metric.label.VALUE} cuando crees consultas de PromQL en Google Cloud.

metric_or_resource.labels

Esta variable renderiza todos los valores de etiquetas de métricas y recursos como una lista ordenada de pares key-value. Si una etiqueta de métrica y una de recurso tienen el mismo nombre, solo se renderiza la etiqueta de métrica.

Cuando migras una regla de alerta de Prometheus, las plantillas de campo de alerta de Prometheus {{$labels}} y {{humanize $labels}} aparecen como ${metric_or_resource.labels} en la configuración de la documentación de la política de alertas.

metric_or_resource.label.KEY
  • Si KEY es una etiqueta válida, esta variable se renderiza en la notificación como el valor de ${metric.label.KEY}.
  • Si KEY es un recurso válido, esta variable se renderiza en la notificación como el valor de ${resource.label.KEY}.
  • Si KEY no es una etiqueta ni un recurso válidos, esta variable se renderiza en la notificación como una cadena vacía.

Cuando migras una regla de alerta de Prometheus, las plantillas de campo de alerta de Prometheus {{$labels.KEY}} y {{humanize $labels.KEY}} aparecen como ${metric_or_resource.labels.KEY} en la configuración de la documentación de la política de alertas.

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 solo pueden contener 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,3
Para 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 las etiquetas de metadatos de recursos definidas por el usuario mediante resource.label.KEY. Usa metadata.user_label.KEY.

Notas de uso

  • Solo se admiten las variables en la tabla. No puedes combinarlas 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 se muestra 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 de una etiqueta de métrica es nula.

Ejemplo

En el siguiente ejemplo, se muestran las versiones de la consola de Google Cloud y la API de Cloud Monitoring de la documentación de la plantilla para una política de alertas de uso de CPU, y la documentación renderizada que aparece en el cuerpo de una notificación. En este ejemplo, se usa un correo electrónico para el tipo de canal de notificaciones. La plantilla de documentación incluye varias variables para resumir el incidente y hacer referencia a los recursos de REST de condición y política de alertas.

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 90% for over 15 minutes.

### Additional resource information

Condition resource name: ${condition.name}
Alerting policy resource name: ${policy.name}

### Troubleshooting and Debug References

Repository with debug scripts: example.com
Internal troubleshooting guide: example.com
${resource.type} dashboard: example.com

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 90% for over 15 minutes.\n\n### Additional resource information\n\nCondition resource name: ${condition.name}  \nAlerting policy resource name: ${policy.name}  \n\n### Troubleshooting and Debug References\n    \nRepository with debug scripts: example.com  \nInternal troubleshooting guide: example.com  \n${resource.type} dashboard: example.com",
"mimeType": "text/markdown",
"subject": "Alert: ${metric.display_name} exceeded"
}

Formato de las notificaciones

Ejemplo de cómo se procesa la documentación en una notificación.

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 y metric.label.KEY pueden tener valores null si tu política de alertas usa agregación de series cruzadas (reducción); por ejemplo, calcular la SUMA en cada una de las 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 como null 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 se resuelven solo en las notificaciones enviadas mediante los siguientes canales de notificación:

  • Correo electrónico
  • Slack
  • Pub/Sub, versión 1.2 del esquema JSON
  • Webhooks, versión 1.2 del esquema JSON
  • PagerDuty, versión 1.2 de esquema JSON

Las variables no se resuelven, pero aparecen como cadenas como ${varname}, en otros contextos, incluidos los siguientes:

  • En la página Detalles del incidente de la consola de Google Cloud
  • En notificaciones enviadas mediante otros canales de notificaciones

Usa controles de 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 esto para vincular la notificación a un ID de usuario específico. Supongamos que incluyes una cadena como esta en el campo de documentación:

<@backendoncall> policy ${policy.display_name} triggered an incident

Cuando el canal de Slack relevante recibe el campo de documentación como parte de la notificación, esta línea activa un mensaje adicional para el ID de usuario backendoncall que, por ejemplo, policy High CPU rate of change triggered an incident. La mención debe referirse al ID del usuario, no al nombre.

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.