Cómo usar Markdown y variables en plantillas de documentación

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

Uso de Markdown

El campo de documentación admite el siguiente subconjunto de etiquetado de Markdown:

  • Encabezados, indicados por caracteres hash iniciales.
  • Listas sin ordenar, indicadas por los caracteres inicial, menos o asterisco.
  • Listas ordenadas, indicadas por un número inicial seguido de un punto
  • Se trata de texto en cursiva, con guiones bajos simples o asteriscos alrededor de una frase.
  • Texto en negrita, indicado por guiones bajos dobles o asteriscos alrededor de una frase
  • Vínculos, indicados por la sintaxis [link text](url).

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 con el formato ${varname}. Cuando el documento se envía con una notificación, la string ${varname} se reemplaza por el valor de varname. En la siguiente captura de pantalla, se muestra la documentación incluida en una notificación por correo electrónico, creada a partir de la plantilla de documentación especificada para una política de alertas:

Documentación incluida en el correo electrónico

Si deseas obtener más información sobre cómo crear una plantilla de documentación para una política de alertas, consulta el paso opcional para especificar la documentación que se incluirá en las notificaciones.

Las siguientes variables están disponibles para su uso en los campos de documentación:

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.
metadata.system_label.KEY El valor de la etiqueta de metadatos del recurso que proporciona el sistema KEY.1
metadata.user_label.KEY El valor de la etiqueta de metadatos del recurso definido por el usuario KEY.1,4
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.

Los valores deben contener un prefijo con un dígito, una letra, una barra diagonal (/) o un signo igual (=). Todos los demás prefijos no están permitidos. Si un valor contiene un prefijo no admitido, el valor no se informa.

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,2.
project El ID del proyecto de alcance de un alcance 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,3,4
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 Las etiquetas de usuario en una política solo se pueden configurar con la API de Monitoring.
3 Para recuperar el valor de la etiqueta project_id en un recurso supervisado en la política de alertas, usa ${resource.project}.
4 No puedes acceder a las etiquetas de metadatos de recursos definidas por el usuario con resource.label.KEY.. Usa metadata.user_label.KEY en su lugar.

Valores null

Los valores para las variables metric.*, resource.* y metadata.* se obtienen 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 la agregación de series cruzadas (reducción), por ejemplo, cuando calculas la SUMA de cada una de las series temporales que coincidan 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 muestran como null cuando la variable se reemplaza por su valor. Todas las etiquetas se conservan cuando no hay agregación de series cruzadas.
  • 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.

Otras 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 procesa 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, se ven 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.

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 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 relevante de Slack recibe el campo de documentación como parte de la notificación, esta línea activa un mensaje adicional para el usuario backendoncall que, por ejemplo, indica policy High CPU rate of change triggered an incident.

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.