Anota 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 incidentes recursos y 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 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 administrarlas y ordenarlas por asunto.

Los asuntos tienen un límite de 255 caracteres. Si no defines un asunto en tu documentación, Cloud Monitoring determina 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, en el encabezado Documentación de políticas
• PagerDuty
• Pub/Sub
• Slack
• Webhooks

Te recomendamos que configures tu contenido de modo que los equipos de respuesta a 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 información sobre los recursos relevantes.

El contenido de la documentación admite lo siguiente:

• Texto sin formato
• Variables
• Controles específicos del canal

• Markdown en canales de notificación que no son de Slack

API de Cloud Monitoring

Para configurar el contenido de la documentación, usa el campo content de la política de alertas documentation.

Consola de Google Cloud

Para configurar el contenido de la documentación, usa el campo Documentación en la sección Notificaciones y nombre de la página Crear política de alertas.

Vínculos

Puedes agregar vínculos a tu documentación para que los equipos de 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, en el 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.

La siguiente configuración 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 las notificaciones puedan acceder al playbook correcto según el 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, en el encabezado Documentación de políticas
• PagerDuty
• Pub/Sub
• Slack
• Webhooks

Para agregar vínculos al contenido de tu documentación, inclúyelos en el campo Documentación de tu política de alertas. Por ejemplo, en la siguiente documentación, se enumera una URL para una guía de cliente:

### Troubleshooting and Debug References

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

Nota: La consola de Google Cloud no admite la configuración del objeto Links para las políticas de alertas.

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 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. 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 en formato ${varname}. Cuando el documento 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ído 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 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	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 (=), la supervisión omite la etiqueta de las notificaciones. Cuando migras una regla de alerta de Prometheus, las plantillas de campos 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.label.metadata_system_VALUE	Hace referencia a una etiqueta del sistema de metadatos de PromQL, en la que VALUE es el nombre específico de la etiqueta, 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, en la que VALUE es el nombre específico de la etiqueta, como region o name. Ejemplo de uso: ${metric.label.metadata_user_name}.
metric_or_resource.labels	Esta variable renderiza todos los valores de las etiquetas de métricas y 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 renderiza la etiqueta de métrica. Cuando migras una regla de alerta de Prometheus, las plantillas de campos 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 alertas de Prometheus, las plantillas de campos 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 en minúscula, 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.

¹ 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.
² Para recuperar el valor de la etiqueta project_id en un recurso supervisado en la política de alertas, usa ${resource.project}.
³ 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.

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, 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.
• 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.

Nota: Las etiquetas que agregues a las métricas basadas en registros no se pueden usar en expresiones de plantilla. Sin embargo, puedes mostrar estas etiquetas en las leyendas de los gráficos y filtrar las series temporales por los valores de las etiquetas.

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. 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 solo se resuelven en las notificaciones que se envían con los siguientes canales de notificación:

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

Nota: Las variables no se resuelven, pero aparecen como cadenas como ${varname}, en otros contextos, en las notificaciones que se envían con otros canales de notificación.

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 notification a un ID de usuario específico. Las menciones no pueden incluir 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 relevante de Slack 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 envía al usuario podría contener información relevante de la notificación, por ejemplo, "Incident created based on policy High CPU rate of change".

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 consola de Google Cloud y de la API de Cloud Monitoring de la documentación de la plantilla para una política de alertas de utilización de la CPU. En estos ejemplos, se usa un correo electrónico para el tipo de canal de notificaciones. Las plantillas de documentación incluyen varias variables para resumir el incidente y hacer referencia a la política de alertas y a los recursos REST de condiciones.

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:

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: