Anote notificações com documentação definida pelo utilizador

Esta página descreve como pode configurar a documentação da política de alertas para que as notificações forneçam aos responsáveis pela resposta a incidentes recursos e informações adicionais para a resolução de incidentes.

Estrutura da documentação

A documentação de uma política de alertas consiste num assunto, conteúdo e links. Pode configurar a documentação na Google Cloud consola, na API Cloud Monitoring e na CLI Google Cloud.

Assuntos

O assunto da sua documentação aparece no assunto das notificações de incidentes relacionados com a sua política de alertas. Os destinatários das notificações podem gerir e ordenar as respetivas notificações por assunto.

As linhas de assunto estão limitadas a 255 carateres. Se não definir um assunto na documentação, o Cloud Monitoring determina a linha de assunto. As linhas de assunto suportam texto simples e variáveis.

Conteúdo

O conteúdo da sua documentação aparece nos seguintes tipos de notificações:

• Email, na secção Documentação de políticas
• PagerDuty
• Pub/Sub
• Slack
• Webhooks

Recomendamos que configure o seu conteúdo para que os responsáveis pela resposta a incidentes possam ver os passos de correção e as informações sobre incidentes nas notificações relacionadas com a sua política de alertas. Por exemplo, pode configurar a documentação para incluir um resumo do incidente e informações sobre recursos relevantes.

O conteúdo da documentação suporta o seguinte:

• Texto simples
• Variáveis
• Controlos específicos do canal

• Redução de

Links

Pode adicionar links à sua documentação para que os responsáveis pela resposta a incidentes possam aceder a recursos como manuais de procedimentos, repositórios e Google Cloud painéis de controlo a partir de uma notificação.

A API Cloud Monitoring permite-lhe definir um objeto que contém os links mais relevantes para os inquiridos. Embora a Google Cloud consola não tenha um campo especificamente para links, pode adicionar uma secção para links no corpo da documentação.

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

### Troubleshooting and Debug References

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

Markdown no conteúdo da documentação

Pode usar o Markdown para formatar o conteúdo da documentação. O conteúdo da documentação suporta o seguinte subconjunto de etiquetagem Markdown:

• Cabeçalhos, indicados por carateres de hash iniciais.
• Listas não ordenadas, indicadas por carateres iniciais de mais, menos ou asterisco.
• Listas ordenadas, indicadas por um número inicial seguido de um ponto.
• Texto em itálico, indicado por carateres de sublinhado ou asteriscos únicos à volta de uma expressão.
• Texto em negrito, indicado por dois carateres de sublinhado ou asteriscos à volta de uma expressão.
• Links, indicados pela sintaxe [link text](url). Para adicionar links à sua notificação, recomendamos que use a API Cloud Monitoring e configure o objeto Link.

Para mais informações sobre esta etiquetagem, consulte qualquer referência de Markdown, por exemplo, o guia de Markdown.

Variáveis na documentação

Para personalizar o texto na sua documentação, pode usar variáveis no formato ${varname}. Quando a documentação é enviada com uma notificação, a string ${varname} é substituída por um valor extraído do recurso Google Cloud correspondente, conforme descrito na tabela seguinte.

¹ Por exemplo, ${resource.label.zone} é substituído pelo valor da etiqueta zone. Os valores destas variáveis estão sujeitos a agrupamento. Consulte os nullvalores para mais informações.
² Para obter o valor da etiqueta project_id num recurso monitorizado na política de alertas, use ${resource.project}.
³ Não pode aceder às etiquetas de metadados de recursos definidos pelo utilizador através de resource.label.KEY.. Em alternativa, use metadata.user_label.KEY.

Notas de utilização

• Apenas são suportadas as variáveis na tabela. Não pode combiná-los em expressões mais complexas, como ${varname1 + varname2}.
• Para incluir a string literal ${ na sua documentação, escape o símbolo $ com um segundo símbolo $, e $${ é renderizado como ${ na sua documentação.
• Estas variáveis são substituídas pelos respetivos valores apenas nas notificações enviadas através de canais de notificação. Na Google Cloud consola, quando a documentação é apresentada, vê as variáveis e não os valores. Os exemplos na consola incluem as descrições de incidentes e a pré-visualização da documentação quando cria uma política de alertas.
• Verifique se as definições de agregação da condição não eliminam a etiqueta. Se a etiqueta for eliminada, o valor da etiqueta na notificação é null. Para mais informações, consulte o artigo A variável de uma etiqueta de métrica é nula.

Valores null

Os valores das variáveis metric.*, resource.* e metadata.* são derivados de séries cronológicas. Os respetivos valores podem ser null se não forem devolvidos valores da consulta de séries cronológicas.

• As variáveis resource.label.KEY e metric.label.KEY podem ter valores null se a sua política de alertas usar a agregação de várias séries (redução), por exemplo, calcular a SOMA em cada uma das séries cronológicas que correspondem a um filtro. Quando usa a agregação de várias séries, todas as etiquetas não usadas no agrupamento são ignoradas e, como resultado, são renderizadas como null quando a variável é substituída pelo respetivo valor. Todas as etiquetas são mantidas quando não existe agregação entre séries. Para mais informações, consulte o artigo A variável de uma etiqueta de métrica é nula.

• Os valores das variáveis metadata.* só estão disponíveis se as etiquetas forem explicitamente incluídas no filtro ou no agrupamento de uma condição para agregação de várias séries. Ou seja, tem de fazer referência à etiqueta de metadados no filtro ou no agrupamento para que tenha um valor para o modelo.

Resolução variável

As variáveis nos modelos de documentação só são resolvidas nas notificações enviadas através dos seguintes canais de notificação:

• Email
• Google Chat
• Slack
• Pub/Sub, versão 1.2 do esquema JSON
• Webhooks, versão 1.2 do esquema JSON
• PagerDuty, versão 1.2 do esquema JSON

Controlos do canal

O texto no campo de documentação também pode incluir carateres especiais usados pelo próprio canal de notificação para controlar a formatação e as notificações.

Por exemplo, o Slack usa @ para menções. Pode usar @ para associar a notificação a um ID de utilizador específico. As menções não podem incluir nomes. Suponhamos que inclui uma string como esta no campo de documentação:

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

Quando o campo de documentação é recebido pelo canal do Slack relevante como parte da notificação, a string anterior faz com que o Slack envie uma mensagem adicional para o ID do utilizador backendoncall. A mensagem enviada pelo Slack ao utilizador pode conter informações relevantes da notificação; por exemplo, "Incidente criado com base na política de taxa de alteração elevada da CPU".

Estas opções adicionais são específicas dos canais. Para mais informações sobre o que pode estar disponível, consulte a documentação fornecida pelo fornecedor do canal.

Exemplo

O exemplo seguinte mostra as versões da Google Cloud consola e da API Cloud Monitoring da documentação de modelos para uma política de alertas de utilização da CPU. Estes exemplos usam um email para o tipo de canal de notificação. Os modelos de documentação incluem várias variáveis para resumir o incidente e fazer referência aos recursos REST da política de alerta e da condição.

  "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