Anotar notificaciones con documentación definida por el usuario

En esta página, se describe cómo puedes configurar la documentación de tu política de alertas a fin de que las notificaciones proporcionen a los responsables de la respuesta ante incidentes información adicional y recursos para la resolución de incidentes.

Estructura de la documentación

La documentación de una política de alertas consta de un tema, contenido y vínculos. Puedes configurar la documentación en la consola de Google Cloud, la API de Cloud Monitoring y 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 administrar y ordenar las notificaciones por tema.

El asunto tiene un límite de 255 caracteres. Si no defines un tema en tu documentación, entonces Cloud Monitoring determinará 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 configurar tu contenido para que los agentes de respuesta ante 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 la documentación para que incluya un resumen del incidente y la información sobre los recursos relevantes.

El contenido de la documentación admite texto sin formato, Markdown, variables y controles específicos del canal.

API de Cloud Monitoring

Configura el contenido de la documentación con el campo content de la política de alertas documentation.

Consola de Google Cloud

Configura el contenido de la documentación con el campo Documentación en la sección Notificaciones y nombre de la página Crear política de alertas.

Puedes agregar vínculos a la 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, debajo del 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.

En la siguiente configuración, se 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 la notificación puedan acceder a la guía correcta en función del 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, debajo del encabezado Documentación sobre políticas
  • PagerDuty
  • Pub/Sub
  • Slack
  • Webhooks

Puedes agregar vínculos al contenido de tu documentación si los incluyes en el campo Documentación de tu política de alertas. Por ejemplo, la siguiente documentación enumera una URL para la guía del 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, te recomendamos que uses el objeto Link para configurar vínculos para 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 la documentación 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, 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ída 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 del recurso definido 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.

Cuando migra una regla de alertas 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 creas 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 migra una regla de alertas 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 válida ni un recurso válido, esta variable se renderiza en la notificación como una cadena vacía.

Cuando migra una regla de alertas 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 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 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 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, su valor en la notificación es null. Para obtener más información, consulta La variable de 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 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 se calcula 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 que se envían mediante los siguientes canales de notificaciones:

  • 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 notificación con un ID del usuario específico. Las menciones no pueden tener 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 un mensaje adicional al ID de usuario backendoncall. El mensaje que Slack le envía al usuario puede 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

En el siguiente ejemplo, se muestran las versiones de la documentación de la plantilla de la consola de Google Cloud y la API de Cloud Monitoring para una política de alertas de uso de CPU. Estos ejemplos usan un correo electrónico para el tipo de canal de notificaciones. Las plantillas de documentación incluyen muchas variables para resumir el incidente, hacer referencia a la política de alertas y acondicionar los recursos de REST.

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:

Ejemplo de cómo se renderiza la documentación en una notificación. Los vínculos se muestran en la sección “Vínculos rápidos”.

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

En la siguiente imagen, se muestra cómo aparece esta plantilla en una notificación por correo electrónico:

Ejemplo de cómo se renderiza la documentación en una notificación. Los vínculos se muestran debajo del encabezado “Solución de problemas y referencias de depuración”.