Anotar alertas con documentación definida por el usuario

En esta página, se describe el contenido que puedes incluir en el campo de la documentación de una política de alertas. Este campo admite texto sin formato, Markdown, variables y controles específicos de canal.

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 adaptar el contenido de tu documentación, puedes usar variables en formato ${varname}. Cuando la documentación se envía con una notificación, la string ${varname} se reemplaza por un valor obtenido 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. Para obtener solo alertas basadas en registros, 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 del recurso definida 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 (/) o un signo igual (=), Monitoring omite la etiqueta de las notificaciones.

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
A fin de 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 en su lugar.

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 Google Cloud Console, 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.

Ejemplo

En el siguiente ejemplo, se muestra la documentación de plantillas de una política de alertas de uso de CPU y la documentación renderizada que aparece en un correo electrónico de notificación. La plantilla de documentación incluye varias variables para resumir el incidente y hacer referencia a la política de alertas y a la condición de recursos REST.

Vista previa

## 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

Formato de notificación

Ejemplo de cómo se renderiza 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 (reducción), por ejemplo, para 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.
  • 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 con los siguientes canales de notificaciones:

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

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

  • En la página Detalles del incidente de Google Cloud Console.
  • En las notificaciones enviadas a través de 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 usarla para vincular la notificación con un ID del usuario específico. Supongamos que incluyes una string 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 del usuario backendoncall que, por ejemplo, policy High CPU rate of change triggered an incident. La mención debe hacer referencia a un ID del usuario, no a un 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.