Anotar alertas com documentação definida pelo usuário

Nesta página, descrevemos como configurar a documentação da política de alertas para personalizar o corpo e a linha de assunto das suas notificações. Os campos de documentação são compatíveis com texto simples, Markdown, variáveis e controles específicos de canal.

Adicionar informações à notificação

É possível fornecer aos responsáveis pela resposta a alertas etapas de remediação e informações sobre o incidente na notificação, especificando esse conteúdo ao criar a política de alertas. Por exemplo, é possível configurar a política de alertas para incluir links para um playbook interno em todas as notificações.

Para ver um exemplo de implementação, consulte a seção Exemplo desta página.

Configurar a linha de assunto das notificações

É possível gerenciar e classificar suas notificações especificando a linha de assunto delas. As linhas de assunto são limitadas a 255 caracteres. Se você não definir um assunto na documentação, o Cloud Monitoring determinará a linha de assunto.

É possível configurar a linha de assunto ao usar a API Cloud Monitoring, a Google Cloud CLI ou o console do Google Cloud.

Para ver um exemplo de implementação, consulte a seção Exemplo desta página.

Como usar Markdown

O campo de 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 mais informações sobre essa tag, consulte qualquer referência do Markdown, por exemplo, Guia do Markdown.

Como usar variáveis

Para personalizar o texto na sua documentação, use 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 correspondente do Google Cloud, 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.
log.extracted_label.KEY O valor do rótulo KEY, extraído de uma entrada de registro. Apenas para alertas com base em registros. Para mais informações, consulte Criar um alerta com base em registros (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 do 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.

Quando você migra uma regra de alerta do Prometheus, os modelos de campo de alerta {{$value}} e {{humanize $value}} do Prometheus aparecem como ${metric.label.VALUE} na configuração da documentação da política de alertas. Nesse caso, VALUE contém o valor da consulta PromQL.

Também é possível usar ${metric.label.VALUE} ao criar consultas do PromQL no Google Cloud.

metric_or_resource.labels

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

Quando você migra uma regra de alerta do Prometheus, os modelos de campo de alerta {{$labels}} e {{humanize $labels}} do Prometheus 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álidos, essa variável será renderizada na notificação como uma string vazia.

Quando você migra uma regra de alerta do Prometheus, os modelos de campo de alerta {{$labels.KEY}} e {{humanize $labels.KEY}} do Prometheus 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 de 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 na 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.. Em vez disso, use metadata.user_label.KEY.

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.
  • Essas variáveis são substituídas por seus valores apenas em notificações enviadas por meio de canais de notificação. No console do Google Cloud, quando a documentação é exibida, são exibidas as variáveis, não os valores. Exemplos no console incluem as descrições de incidentes e a visualização da documentação ao criar uma política de alertas.
  • Garanta que as configurações de agregação da condição não eliminem 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.

Exemplo

O exemplo a seguir mostra as versões do console do Google Cloud e da API Cloud Monitoring da documentação de modelo de uma política de alertas de utilização da CPU e a documentação renderizada que aparece no corpo de uma notificação. Nesse exemplo, um e-mail é usado para o tipo de canal de notificação. O modelo de documentação inclui diversas variáveis para resumir o incidente e fazer referência aos recursos REST de condição e política de alertas.

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 90% for over 15 minutes.

### Additional resource information

Condition resource name: ${condition.name}
Alerting policy resource name: ${policy.name}

### Troubleshooting and Debug References

Repository with debug scripts: example.com
Internal troubleshooting guide: example.com
${resource.type} dashboard: example.com

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 90% for over 15 minutes.\n\n### Additional resource information\n\nCondition resource name: ${condition.name}  \nAlerting policy resource name: ${policy.name}  \n\n### Troubleshooting and Debug References\n    \nRepository with debug scripts: example.com  \nInternal troubleshooting guide: example.com  \n${resource.type} dashboard: example.com",
"mimeType": "text/markdown",
"subject": "Alert: ${metric.display_name} exceeded"
}

Formatar na notificação

Exemplo de como a documentação é renderizada em uma notificação.

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, calculando a SUM em cada uma das séries temporais que correspondem 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 apenas nas notificações enviadas usando os seguintes canais de notificação:

  • E-mail
  • Slack
  • Pub/Sub, esquema JSON versão 1.2
  • Webhooks, esquema JSON versão 1.2
  • PagerDuty, esquema JSON versão 1.2

As variáveis não são resolvidas, mas aparecem como strings como ${varname}, em outros contextos, incluindo:

  • Na página Detalhes do incidente no console do Google Cloud.
  • Em notificações enviadas por outros canais de notificação.

Como usar controles de canal

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. Esse método pode ser usado para vincular a notificação a um ID do usuário específico. Suponha que você inclua uma string como esta no campo de documentação:

<@backendoncall> policy ${policy.display_name} triggered an incident

Quando o campo de documentação é recebido pelo canal do Slack relevante como parte da notificação, essa linha aciona uma mensagem adicional para o ID de usuário backendoncall que, por exemplo, é policy High CPU rate of change triggered an incident. A menção precisa se referir a um ID do usuário, não a um nome.

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.