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 para que las notificaciones proporcionen a los responsables de responder a incidentes recursos e información adicional para resolverlos.

Estructura de la documentación

La documentación de una política de alertas consta de un asunto, contenido y enlaces. Puedes configurar la documentación en la Google Cloud consola, la API Cloud Monitoring y la CLI de Google Cloud.

Asuntos

El asunto de la documentación aparece en el asunto de las notificaciones de incidentes relacionados con la política de alertas. Los destinatarios de las notificaciones pueden gestionar y ordenar sus notificaciones por asunto.

Los asuntos tienen un límite de 255 caracteres. Si no define un asunto en su documentación, Cloud Monitoring determinará la línea del asunto. En las líneas de asunto se pueden usar texto sin formato y variables.

API de Cloud Monitoring

Configura el asunto de la notificación mediante el campo subject de la política de alertas documentation.

Google Cloud consola

Configura el asunto de la notificación en el campo Asunto de la notificación de 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, en la sección Documentación de la política
  • PagerDuty
  • Pub/Sub
  • Slack
  • Webhooks

Te recomendamos que configures tu contenido para que los responsables de responder a incidentes puedan ver los pasos de corrección y la información de los incidentes en las notificaciones relacionadas con tu política de alertas. Por ejemplo, puedes configurar la documentación para que incluya un resumen del incidente e información sobre los recursos pertinentes.

El contenido de la documentación admite lo siguiente:

API de Cloud Monitoring

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

Google Cloud consola

Configura el contenido de la documentación mediante el campo Documentation (Documentación) de la sección Notifications and name (Notificaciones y nombre) de la página Create alerting policy (Crear política de alertas).

Puedes añadir enlaces a tu documentación para que los responsables de responder a incidentes puedan acceder a recursos como guías, repositorios y Google Cloud paneles de control desde una notificación.

La API Cloud Monitoring te permite definir un objeto que contenga los enlaces más relevantes para los responsables. Aunque la consola Google Cloud no tiene un campo específico para enlaces, puedes añadir una sección para enlaces en el cuerpo de la documentación.

API de Cloud Monitoring

Puedes añadir enlaces a tu documentación definiendo uno o varios objetos Link en el campo links de la política de alertas documentation. Cada objeto Link consta de un display_name y un url. Puedes incluir hasta tres enlaces en tu documentación.

En la siguiente configuración se muestra el campo links con un objeto Link que representa una URL a un manual de procedimientos de incidentes. La URL incluye una variable para que los destinatarios de la notificación puedan acceder al playbook correcto en función del recurso monitorizado en el que se haya producido el incidente:

"links" [
  {
    "displayName": "Playbook",
    "url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
  }
]

Los enlaces de documentación que se añaden mediante el campo Link aparecen en los siguientes tipos de notificaciones:

  • Correo, en la sección Enlaces rápidos
  • PagerDuty
  • Pub/Sub
  • Webhooks

Google Cloud consola

Puedes añadir enlaces al contenido de tu documentación incluyéndolos en el campo Documentation (Documentación) de tu política de alertas. Por ejemplo, en la siguiente documentación se indica una URL de un manual de estrategias para clientes:

### Troubleshooting and Debug References

Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}

Los enlaces a la documentación que se añaden mediante la consola Google Cloud aparecen con el resto del contenido de la documentación en los siguientes tipos de notificaciones:

  • Correo, en la sección Documentación de la política
  • PagerDuty
  • Pub/Sub
  • Slack
  • Webhooks

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 almohadilla iniciales.
  • Listas sin ordenar, indicadas por los caracteres iniciales más, menos o asterisco.
  • Listas ordenadas, indicadas por un número inicial seguido de un punto.
  • Texto en cursiva, indicado por guiones bajos o asteriscos simples alrededor de una frase.
  • Texto en negrita, indicado por dos guiones bajos o asteriscos alrededor de una frase.
  • Enlaces, indicados con la sintaxis [link text](url). Para añadir enlaces a tu notificación, te recomendamos que uses la API Cloud Monitoring y configures el objeto Link.

Para obtener más información sobre este etiquetado, consulta cualquier referencia de Markdown, como la guía de Markdown.

Variables en la documentación

Para personalizar el texto de la documentación, puedes usar variables con el formato ${varname}. Cuando la documentación se envía con una notificación, la cadena ${varname} se sustituye por un valor extraído del recurso correspondiente, tal como se describe en la siguiente tabla. Google Cloud

Variable Valor
condition.name Nombre de recurso 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 políticas de alertas basadas en registros. Para obtener más información, consulta Crear una política de alertas basada en registros con la API Monitoring.
metadata.system_label.KEY Valor de la etiqueta de metadatos de recursos proporcionada por el sistema KEY.1
metadata.user_label.KEY Valor de la etiqueta de metadatos de recursos definida por el usuario KEY.1,3
metric.type El tipo de métrica, como
compute.googleapis.com/instance/cpu/utilization.
metric.display_name Nombre visible del tipo de métrica, como CPU utilization.
metric.label.KEY

Valor de la etiqueta de métrica KEY.1
Para encontrar las etiquetas asociadas al tipo de métrica, consulta la lista de métricas.

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

Cuando migras una regla de alertas de Prometheus, las plantillas de campos de alertas 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, ${metric.label.value} contiene el valor de activación de la regla de alerta de Prometheus.

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

Hace referencia a una etiqueta de metadatos del sistema PromQL, donde VALUE es el nombre de la etiqueta específica, como region o version.

Ejemplo de uso: ${metric.label.metadata_system_version}.
metric.label.metadata_user_VALUE

Hace referencia a una etiqueta de usuario de metadatos de PromQL, donde VALUE es el nombre de la etiqueta específica, como region o name.

Ejemplo de uso: ${metric.label.metadata_user_name}.
metric_or_resource.labels

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

Cuando migras una regla de alertas de Prometheus, las plantillas de campos de alertas 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 muestra en la notificación como el valor de ${metric.label.KEY}.
  • Si KEY es un recurso válido, esta variable se muestra 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 mostrará en la notificación como una cadena vacía.

Cuando migras una regla de alertas de Prometheus, las plantillas de campos de alertas 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 Nombre de 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 empezar por 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 ámbito de un ámbito de métricas, como a-gcp-project.
resource.type El tipo de recurso monitorizado, como gce_instance.
resource.project El ID de proyecto del recurso monitorizado 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 al tipo de recurso supervisado, consulta la lista de recursos.

1 Por ejemplo, ${resource.label.zone} se sustituye por el valor de la etiqueta zone. Los valores de estas variables están sujetos a agrupaciones. Consulta los valores de null para obtener más información.
 2 Para obtener el valor de la etiqueta project_id de un recurso monitorizado en la política de alertas, usa ${resource.project}.
 3 No puedes acceder a las etiquetas de metadatos de recursos definidos por el usuario mediante resource.label.KEY.. Usa metadata.user_label.KEY en su lugar.

Notas de uso

  • Solo se admiten las variables de la tabla. No puedes combinarlos en expresiones más complejas, como ${varname1 + varname2}.
  • Para incluir la cadena literal ${ en la documentación, escapa el símbolo $ con otro símbolo $. De esta forma, $${ se representará como ${ en la documentación.
  • Estas variables se sustituyen por sus valores solo en las notificaciones enviadas a través de canales de notificación. En la Google Cloud consola, cuando se muestra la documentación, ves las variables, no los valores. Por ejemplo, en la consola se incluyen las descripciones de los incidentes y la vista previa de la documentación al crear una política de alertas.
  • Verifica 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 Variable for a metric label is null (La variable de una etiqueta de métrica es nula).

null valores

Los valores de las variables metric.*, resource.* y metadata.* se derivan de series temporales. Sus valores pueden ser null si la consulta de serie temporal no devuelve ningún valor.

  • Las variables resource.label.KEY y metric.label.KEY pueden tener valores null si tu política de alertas usa la agregación entre series (reducción). Por ejemplo, si calcula la SUMA de cada una de las series temporales que coinciden con un filtro. Cuando se usa la agregación entre series, se quitan las etiquetas que no se usan en la agrupación y, como resultado, se representan como null cuando la variable se sustituye por su valor. Todas las etiquetas se conservan cuando no hay agregación entre series. Para obtener más información, consulta Variable for a metric label is null (La variable de una etiqueta de métrica es nula).

  • Los valores de las variables metadata.* solo están disponibles si las etiquetas se incluyen explícitamente en el filtro o la agrupación de una condición para la agregación entre series. Es decir, debes hacer referencia a la etiqueta de metadatos en el filtro o en la agrupación para que tenga un valor en la plantilla.

Resolución variable

Las variables de las plantillas de documentación solo se resuelven en las notificaciones que se envían a través de los siguientes canales de notificación:

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

Controles del canal

El texto del campo de documentación también puede incluir caracteres especiales que utilice el propio canal de notificaciones para controlar el formato y las notificaciones.

Por ejemplo, Slack usa @ para las menciones. Puedes usar @ para vincular la notificación a un ID de usuario específico. Las menciones no pueden incluir nombres. Supongamos que incluye una cadena como esta en el campo de documentación:

<@backendoncall> Incident created based on policy ${policy.display_name}

Cuando el campo de documentación se recibe en el canal de Slack correspondiente 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 envía Slack al usuario puede contener información relevante de la notificación; por ejemplo, "Incidencia creada a partir de la política Tasa de cambio de CPU alta".

Estas opciones adicionales son específicas de los canales. Para obtener más información sobre lo que puede estar disponible, consulta la documentación proporcionada por el proveedor del canal.

Ejemplo

En el siguiente ejemplo se muestran las versiones de la consola Google Cloud y de la API Cloud Monitoring de la documentación de la plantilla de una política de alertas de utilización de CPU. En estos ejemplos se usa un correo electrónico para el tipo de canal de notificación. Las plantillas de documentación incluyen varias variables para resumir el incidente y hacer referencia a los recursos REST de la política de alertas y la condición.

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 muestra la documentación en una notificación. Los enlaces se muestran en la sección &quot;Enlaces rápidos&quot;.

Google Cloud consola 

### 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 muestra la documentación en una notificación. Los enlaces se muestran en el encabezado &quot;Referencias de solución de problemas y depuración&quot;.