Fazer anotações em notificações com documentação definida pelo usuário

Nesta página, descrevemos como configurar a documentação da política de alertas para que as notificações forneçam aos responsáveis por responder aos alertas recursos e informações adicionais para a resolução deles.

Estrutura da documentação

A documentação de uma política de alertas consiste em um assunto, conteúdo e links. É possível configurar a documentação no console Google Cloud , na API Cloud Monitoring e na Google Cloud CLI.

Sujeitos

O assunto da sua documentação aparece no assunto das notificações de alertas relacionados à sua política de alertas. Os destinatários podem gerenciar e classificar as notificações por assunto.

As linhas de assunto são limitadas a 255 caracteres. Se você não definir um assunto na documentação, o Cloud Monitoring vai determinar a linha de assunto. Os assuntos aceitam texto simples e variáveis.

API Cloud Monitoring

Configure a linha de assunto da notificação usando o campo subject da política de alertas documentation.

Console do Google Cloud

Configure a linha de assunto da notificação usando o campo Linha de assunto da notificação na seção Notificações e nome da página Criar política de alertas.

Conteúdo

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

  • E-mail, na seção Documentação da política
  • PagerDuty
  • Pub/Sub
  • Slack
  • Webhooks

Recomendamos configurar seu conteúdo para que os responsáveis por responder a alertas possam ver as etapas de correção e as informações do alerta em notificações relacionadas à sua política de alertas. Por exemplo, é possível configurar a documentação para incluir um resumo do alerta e informações sobre os recursos relevantes.

O conteúdo da documentação é compatível com o seguinte:

API Cloud Monitoring

Configure o conteúdo da documentação usando o campo content da política de alertas documentation.

Console do Google Cloud

Configure o conteúdo da documentação usando o campo Documentação na seção Notificações e nome da página Criar política de alertas.

Você pode adicionar links à sua documentação para que os responsáveis por responder aos alertas possam acessar recursos como manuais, repositórios e painéis do Google Cloud em uma notificação.

Com a API Cloud Monitoring, é possível definir um objeto que contém os links mais relevantes para os atendentes. Embora o console Google Cloud não tenha um campo específico para links, você pode adicionar uma seção para eles no corpo da documentação.

API Cloud Monitoring

É possível adicionar links à documentação definindo um ou mais objetos Link no campo links da política de alertas documentation. Cada objeto Link consiste em um display_name e um url. Você pode ter até três links na documentação.

A configuração a seguir mostra o campo links com um objeto Link que representa um URL para um manual de resposta a alertas. O URL inclui uma variável para que os destinatários da notificação possam acessar o playbook correto com base no recurso monitorado em que o alerta ocorreu:

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

Os links de documentação adicionados usando o campo Link aparecem nos seguintes tipos de notificação:

  • E-mail, na seção Links rápidos
  • PagerDuty
  • Pub/Sub
  • Webhooks

Console do Google Cloud

Para adicionar links ao conteúdo da documentação, inclua-os no campo Documentação da política de alertas. Por exemplo, a documentação a seguir lista um URL para um playbook do cliente:

### Troubleshooting and Debug References

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

Os links de documentação adicionados usando o console Google Cloud aparecem com o restante do conteúdo da documentação nos seguintes tipos de notificação:

  • E-mail, na seção Documentação da política
  • PagerDuty
  • Pub/Sub
  • Slack
  • Webhooks

Markdown no conteúdo da documentação

Use o Markdown para formatar o conteúdo da documentação. O conteúdo da documentação é compatível com o seguinte subconjunto de tags do Markdown:

  • Cabeçalhos, indicados por caracteres de hash iniciais.
  • Listas não ordenadas, indicadas pelos caracteres inicial mais, menos ou asterisco.
  • Listas ordenadas, indicadas por um número inicial seguido por um ponto.
  • Texto iterativo, indicado por sublinhados únicos ou asteriscos em torno de uma frase.
  • Texto em negrito, indicado por sublinhados duplos ou asteriscos ao redor de uma frase.
  • Links, indicados pela sintaxe [link text](url). Para adicionar links à sua notificação, recomendamos usar a API Cloud Monitoring e configurar o objeto Link.

Para mais informações sobre essa tag, consulte qualquer referência do Markdown, por exemplo, Guia do Markdown.

Variáveis na documentação

Para personalizar o texto na documentação, use variáveis do formulário ${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 a seguir.

Variável Valor
condition.name O nome do recurso REST da condição, como
projects/foo/alertPolicies/1234/conditions/5678.
condition.display_name

O nome de exibição de uma condição, como CPU usage increasing rapidly.

Para políticas de alertas com base em registros criadas com a Análise de registros, o valor desse campo é "Log match condition". Para personalizar o valor desse campo, use a API Cloud Monitoring.
log.extracted_label.KEY O valor do rótulo KEY, extraído de uma entrada de registro. Apenas para políticas de alertas com base em registros. Para mais informações, consulte Criar uma política de alertas com base em registros usando a API Monitoring.
metadata.system_label.KEY O valor do rótulo de metadados de recurso fornecido pelo sistema KEY.1
metadata.user_label.KEY O valor do rótulo de metadados de recurso definido pelo usuário KEY.1,3
metric.type O tipo de métrica, como
compute.googleapis.com/instance/cpu/utilization
metric.display_name O nome de exibição do tipo de métrica, como CPU utilization.
metric.label.KEY

O valor do rótulo de métrica KEY.1
Para encontrar os rótulos associados ao tipo de métrica, consulte Lista de métricas.

Quando o valor da variável ${metric.label.KEY} não começa com um dígito, uma letra, uma barra (/) ou um sinal de igual (=), o Monitoring omite o rótulo das notificações.

Ao migrar uma regra de alerta do Prometheus, os modelos de campo de alerta do Prometheus {{$value}} e {{humanize $value}} aparecem como ${metric.label.value} na configuração da documentação da política de alertas. Nesse caso, ${metric.label.value} contém o valor de acionamento da regra de alerta do Prometheus.

Você também pode usar ${metric.label.value} ao criar consultas do PromQL em Google Cloud.
metric.label.metadata_system_VALUE

Faz referência a um rótulo do sistema de metadados do PromQL, em que VALUE é o nome do rótulo específico, como region ou version.

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

Faz referência a um rótulo de usuário de metadados do PromQL, em que VALUE é o nome específico do rótulo, como region ou name.

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

Essa variável renderiza todos os valores de métricas e rótulos de recursos como uma lista classificada de pares key-value. Se um rótulo de métrica e um rótulo de recurso tiverem o mesmo nome, apenas o rótulo de métrica será renderizado.

Ao migrar uma regra de alerta do Prometheus, os modelos de campo de alerta do Prometheus {{$labels}} e {{humanize $labels}} aparecem como ${metric_or_resource.labels} na configuração da documentação da política de alertas.
metric_or_resource.label.KEY
  • Se KEY for um rótulo válido, essa variável será renderizada na notificação como o valor de ${metric.label.KEY}.
  • Se KEY for um recurso válido, essa variável será renderizada na notificação como o valor de ${resource.label.KEY}.
  • Se KEY não for um rótulo nem um recurso válido, essa variável será renderizada na notificação como uma string vazia.

Ao migrar uma regra de alerta do Prometheus, os modelos de campo de alerta do Prometheus {{$labels.KEY}} e {{humanize $labels.KEY}} aparecem como ${metric_or_resource.labels.KEY} na configuração da documentação da política de alertas.
policy.name O nome do recurso REST da política, como projects/foo/alertPolicies/1234.
policy.display_name O nome de exibição de uma política, como High CPU rate of change.
policy.user_label.KEY O valor do rótulo do usuário KEY.1

As chaves precisam começar com letra minúscula. As chaves e os valores podem conter apenas letras minúsculas, dígitos, sublinhados e traços.
project O ID do projeto de escopo de um escopo de métricas, como a-gcp-project.
resource.type O tipo de recurso monitorado, como gce_instance.
resource.project O ID do projeto do recurso monitorado relacionado à política de alertas.
resource.label.KEY O valor do rótulo de recurso KEY.1,2,3
Para encontrar os rótulos associados ao tipo de recurso monitorado, consulte Lista de recursos.

1 Por exemplo, ${resource.label.zone} é substituído pelo valor do rótulo zone. Os valores dessas variáveis estão sujeitos a agrupamento. Consulte os valores de null para mais informações.
 2 Para recuperar o valor do rótulo project_id em um recurso monitorado da política de alertas, use ${resource.project}.
 3 Não é possível acessar rótulos de metadados de recursos definidos pelo usuário usando resource.label.KEY. Use metadata.user_label.KEY em vez disso.

Observações sobre uso

  • Apenas as variáveis na tabela são compatíveis. Não é possível combiná-las em expressões mais complexas como ${varname1 + varname2}.
  • Para incluir a string literal ${ na documentação, insira o símbolo de escape $ com um segundo símbolo $, e $${ será renderizado como ${ na documentação.
  • As políticas de alertas sempre mostram strings de variáveis, como ${varname}.
  • Para alguns canais de notificação, o Cloud Monitoring substitui strings de variáveis, como ${varname}, pelos valores correspondentes. Para mais informações, consulte Resolução de variáveis.
  • Quando o console do Google Cloud mostra a visualização de detalhes de um alerta, ele geralmente substitui strings de variáveis como ${varname} pelos valores correspondentes.
  • Verifique se as configurações de agregação da condição não eliminam o rótulo. Se o rótulo for eliminado, o valor dele na notificação será null. Para mais informações, consulte A variável de um rótulo de métrica é nula.

null valores

Os valores das variáveis metric.*, resource.* e metadata.* são derivados de séries temporais. Os valores delas poderão ser null se nenhum valor for retornado da consulta de série temporal.

  • As variáveis resource.label.KEY e metric.label.KEY podem ter valores null se a política de alertas usar agregação entre séries (redução), por exemplo, calcular a SOMA em cada série temporal que corresponder a um filtro. Ao usar a agregação entre séries, todos os rótulos não usados no agrupamento são descartados e, como resultado, eles são renderizados como null quando a variável é substituída pelo valor. Todos os rótulos são retidos quando não há agregação entre séries. Para mais informações, consulte A variável de um rótulo de métrica é nula.

  • Os valores das variáveis metadata.* estarão disponíveis somente se os rótulos estiverem incluídos explicitamente no filtro de uma condição ou no agrupamento da agregação entre séries. Ou seja, é necessário fazer referência ao rótulo de metadados no filtro ou agrupamento para que ele tenha um valor para o modelo.

Resolução variável

As variáveis em modelos de documentação são resolvidas nos seguintes contextos:

  • Notificações enviadas usando os seguintes canais:
    • E-mail
    • 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
  • A visualização de detalhes do alerta do console Google Cloud .

Controles de canais

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

Por exemplo, o Slack usa @ nas menções. Você pode usar @ para vincular a notificação a um ID de usuário específico. As menções não podem incluir nomes. Suponha que você inclua uma string como esta no campo de documentação:

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

Quando o campo de documentação é recebido pelo canal do Slack em questão como parte da notificação, a string anterior faz com que o Slack envie uma mensagem adicional para o ID do usuário backendoncall. A mensagem enviada pelo Slack ao usuário pode conter informações relevantes da notificação. Por exemplo, "Alerta criado com base na política Alta taxa de alteração da CPU".

Essas opções complementares são específicas para os canais. Para saber mais sobre o que está disponível, consulte a documentação oferecida pelo fornecedor do canal.

Exemplo

O exemplo a seguir mostra as versões do console Google Cloud e da API Cloud Monitoring da documentação de modelo para uma política de alertas de utilização da CPU. Estes exemplos usam um e-mail para o tipo de canal de notificação. Os modelos de documentação incluem várias variáveis para resumir o alerta e referenciar os recursos REST da política de alertas e da condição.

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

A imagem a seguir mostra como esse modelo aparece em uma notificação por e-mail:

Exemplo de como a documentação é renderizada em uma notificação. Os links são mostrados na seção &quot;Links rápidos&quot;.

Console do 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

A imagem a seguir mostra como esse modelo aparece em uma notificação por e-mail:

Exemplo de como a documentação é renderizada em uma notificação. Os links aparecem em um cabeçalho &quot;Referências de solução de problemas e depuração&quot;.