Nesta página, descrevemos como configurar a documentação da política de alertas para que as notificações forneçam aos responsáveis pela resposta informações adicionais para a resolução de incidentes.
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 do Google Cloud, a API Cloud Monitoring e a Google Cloud CLI.
Sujeitos
O assunto da sua documentação aparece como o assunto do notificações de incidentes relacionados à política de alertas. Os destinatários das notificações 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 sua documentação, o Cloud Monitoring vai determinar a linha de assunto. As linhas de assunto são compatíveis com texto simples e variáveis.
API Cloud Monitoring
Configurar 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 No campo Linha de assunto da notificação, Seção Notificações e nome da página Criar política de alertas.
Conteúdo
O conteúdo da sua documentação aparece na notificação a seguir. tipos:
- E-mail, no cabeçalho Documentação da política
- PagerDuty
- Pub/Sub
- Slack
- Webhooks
Recomendamos configurar seu conteúdo para que os responsáveis pelo incidente possam conferir as etapas de correção e as informações do incidente nas notificações relacionadas à sua política de alertas. Por exemplo, é possível configurar de configuração para incluir um resumo do incidente e informações sobre recursos relevantes.
O conteúdo da documentação aceita texto simples, Markdown, variáveis e controles específicos do canal.
API Cloud Monitoring
Configurar 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 no Seção Notificações e nome da página Criar política de alertas.
Links
Você pode adicionar links à sua documentação para que os responsáveis pela resposta a incidentes possam acessar recursos como playbooks, repositórios e painéis do Google Cloud em uma notificação.
API Cloud Monitoring
Os links de documentação configurados na API Cloud Monitoring aparecem na seguintes tipos de notificação:
- E-mail, no cabeçalho Links rápidos
- PagerDuty
- Pub/Sub
- Webhooks
Para configurar um link, adicione um Link
ao
documentation
da política de alertas.
Cada link é representado por um display_name
e um url
. Você pode ter até
há três links em sua documentação.
A configuração a seguir usa links
com um URL
para criar um link
para um playbook de incidentes. O URL inclui uma variável
que os destinatários da notificação possam acessar o playbook correto com base no
recurso monitorado em que o incidente ocorreu:
"links" [
{
"displayName": "Playbook",
"url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
}
]
Console do Google Cloud
Os links de documentação configurados no console do Google Cloud aparecem com o o restante do conteúdo da documentação nos seguintes tipos de notificação:
- E-mail, no cabeçalho Documentação da política
- PagerDuty
- Pub/Sub
- Slack
- Webhooks
Para adicionar links ao conteúdo da documentação, inclua-os no campo Documentação da sua política de alertas. Por exemplo, o a documentação a seguir lista um URL de um playbook do cliente:
### Troubleshooting and Debug References Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}
Markdown no conteúdo da documentação
Use 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)
. No entanto, recomendamos o uso do ObjetoLink
para configurar links para seu conteúdo.
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 da documentação, use variáveis
da forma ${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 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 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 Ao migrar uma regra de alerta do Prometheus, os modelos de campo de alerta do Prometheus Também é possível usar |
metric_or_resource.labels |
Essa variável renderiza todos os valores de métrica e rótulo de recurso como uma lista classificada de pares Ao migrar uma regra de alerta do Prometheus, os modelos de campo de alerta do Prometheus |
metric_or_resource.label.KEY |
Ao migrar uma regra de alerta do Prometheus, os modelos de campo de alerta do Prometheus |
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 somente 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.
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, você vê 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.
- Verifique se as configurações de agregação da condição não eliminam a
rótulo. Se o rótulo for eliminado, o valor dele na tag
notificação é
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
emetric.label.KEY
podem ter valoresnull
se a política de alertas usar agregação (redução) entre séries, por exemplo, calcular a SOMA 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
Variáveis em modelos de documentação são resolvidas somente nas notificações enviados pelos seguintes canais de notificação:
- Google Chat
- Slack
- Pub/Sub, esquema JSON versão 1.2
- Webhooks, esquema JSON versão 1.2
- PagerDuty, esquema JSON versão 1.2
Controles do 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. Você pode usar @
para vincular o
a um ID do 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> 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 usuário
backendoncall
: A mensagem enviada pelo Slack para o usuário
possa conter informações relevantes da notificação; por exemplo,
"Incidente criado com base na política de 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 do Google Cloud e da API Cloud Monitoring do documentação do modelo para uma política de alertas de utilização da CPU. Nestes exemplos, usamos um e-mail para o tipo de canal de notificação. Os modelos de documentação incluem diversas variáveis para resumir o incidente e fazer referência à política de alertas e aos recursos REST de 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 um e-mail notificação:
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 um e-mail notificação: