Esta página foi traduzida pela API Cloud Translation.

Anotar 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 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 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 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 que você configure seu conteúdo para que o incidente os responsáveis pela resposta podem visualizar as etapas de remediação e informações sobre incidentes nas notificações relacionados à 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 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 Objeto Link 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`.¹
`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`.¹ 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 marcador 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, `VALUE` contém o valor da consulta do PromQL. Também é possível usar `${metric.label.VALUE}` ao criar PromQL consultas no Google Cloud.
`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 `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. 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 política de alertas. configuração da documentação.
`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. 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 resposta configuração da documentação da política.
`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`.¹ 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,3 Para encontrar os rótulos associados ao tipo de recurso monitorado, consulte Lista de recursos.

¹ 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.
² Para recuperar o valor do rótulo project_id em um recurso monitorado na política de alertas, use ${resource.project}.
³ Não é possível acessar rótulos de metadados de recursos definidos pelo usuário usando resource.label.KEY. Use metadata.user_label.KEY como alternativa.

Observações sobre uso

Apenas as variáveis na tabela são compatíveis. Não é possível combiná-las 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 documentação for mostrada, 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.
Verifique se 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 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 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 SUM em cada um 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

Variáveis em modelos de documentação são resolvidas somente nas notificações enviados pelos seguintes canais de notificação:

E-mail
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 de usuário específico. Não é possível incluir nomes nas menções. 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:

Exemplo de como a documentação é renderizada em uma notificação. Os links são exibidos na coluna "Links rápidos" nesta seçã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:

Exemplo de como a documentação é renderizada em uma notificação. Os links são exibidos em "Referências de depuração e solução de problemas" cabeçalho.

Anotar notificações com documentação definida pelo usuário

Estrutura da documentação

Sujeitos

API Cloud Monitoring

Console do Google Cloud

Conteúdo

API Cloud Monitoring

Console do Google Cloud

Links

API Cloud Monitoring

Console do Google Cloud

Markdown no conteúdo da documentação

Variáveis na documentação

Observações sobre uso

null valores

Resolução variável

Controles do canal

Exemplo

API Cloud Monitoring

Console do Google Cloud

`null` valores