Nesta página, descrevemos como configurar a documentação da política de alertas para que as notificações forneçam recursos e mais informações aos responsáveis pela resposta a incidentes 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, na API Cloud Monitoring e na Google Cloud CLI.
Sujeitos
O assunto da documentação aparece no assunto das notificações de incidentes relacionados à 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 determinará a linha de assunto. As linhas de assunto são compatíveis com 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, no cabeçalho Documentação da política
- PagerDuty
- Pub/Sub
- Slack
- Webhooks
Recomendamos que você configure seu conteúdo para que os responsáveis pela resposta a incidentes possam ver as etapas de correção e as informações sobre o incidente nas notificações relacionadas à sua política de alertas. Por exemplo, a documentação pode ser configurada para incluir um resumo do incidente e informações sobre os recursos relevantes.
O conteúdo da documentação é compatível com texto simples, Markdown, variáveis e controles específicos de canal.
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.
Links
É possível adicionar links à sua documentação para que os responsáveis pela resposta a incidentes possam acessar recursos como manuais, 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 nos seguintes tipos de notificação:
- E-mail, no cabeçalho Links rápidos
- PagerDuty
- Pub/Sub
- Webhooks
Para configurar um link, adicione um Link
a documentation
da sua política de alertas.
Cada link é representado por um display_name
e um url
. Você pode ter até
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 para 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 restante do conteúdo dela nos seguintes tipos de notificação:
- E-mail, no cabeçalho Documentação da política
- PagerDuty
- Pub/Sub
- Slack
- Webhooks
Inclua links no conteúdo da documentação no campo Documentação da sua política de alertas. Por exemplo, 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 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 usar o 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 na sua 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 retirado do
recurso do 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 . |
log.extracted_label.KEY |
O valor do rótulo KEY , extraído de uma entrada de registro. Somente 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 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 recursos e métricas como uma lista classificada de pares 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 a 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 for exibida, você verá 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.
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
poderão ter valoresnull
se a política de alertas usar agregação entre séries (redução), por exemplo, para calcular a SOMA em cada série temporal que corresponde 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 somente nas notificações enviadas usando os 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 a notificaçã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
outra mensagem 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,
"Incidente 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 do Google Cloud e da API Cloud Monitoring da 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 uma notificação por e-mail:
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: