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 encargados de responder ante 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 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 los incidentes relacionados con tu política de alertas. Los destinatarios de las notificaciones pueden administrar y ordenar sus notificaciones por asunto.

Las líneas de asunto tienen un límite de 255 caracteres. Si no defines un asunto en la documentación, Cloud Monitoring determinará el asunto. Las líneas de asunto admiten texto sin formato y variables.

Contenido

El contenido de tu documentación aparece en los siguientes tipos de notificaciones:

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

Te recomendamos que configures tu contenido para que los encargados de responder ante incidentes puedan ver los pasos de correcció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 pertinentes.

El contenido de la documentación admite lo siguiente:

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

• Markdown

Vínculos

Puedes agregar vínculos a tu documentación para que los encargados de responder a incidentes puedan acceder a recursos como guías, repositorios y paneles de Google Cloud desde una notificación.

La API de Cloud Monitoring te permite definir un objeto que contiene los vínculos más relevantes para los encargados de responder. Si bien la consola de Google Cloud no tiene un campo específico para los vínculos, puedes agregar una sección para ellos en el cuerpo de la documentación.

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

### 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 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 agregar vínculos a tu notificación, te recomendamos que uses la API de Cloud Monitoring y configures el objeto Link.

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 la documentación se envía con una notificación, la cadena ${varname} se reemplaza por un valor extraído del recurso Google Cloud correspondiente, como se describe en la siguiente tabla.

¹ 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, 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.
• 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 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 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 enviadas 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 de canales

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 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, "Se creó un incidente basado en la política 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 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 de la política de alertas y la condición de la API de REST.

  "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"
      }
    ]
  }

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