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 Quando o valor da variável Quando você migra uma regra de alerta do Prometheus, os modelos de campo de alerta Também é possível usar |
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 Quando você migra uma regra de alerta do Prometheus, os modelos de campo de alerta |
metric_or_resource.label.KEY |
Quando você migra uma regra de alerta do Prometheus, os modelos de campo de alerta |
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,3Para 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
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
emetric.label.KEY
podem ter valoresnull
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 comonull
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:
- 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.