Como usar o Markdown e variáveis em modelos de documentação

Esta página descreve o conteúdo que pode ser incluído no campo de documentação de uma política de alertas. Esse campo é compatível com texto simples, Markdown, variáveis e controles específicos do canal.

Como usar o Markdown

O campo de documentação é compatível com o seguinte subconjunto de tags Markdown:

  • Cabeçalhos, indicados por caracteres de hash iniciais.
  • Listas não ordenadas, indicadas pelo sinal de mais inicial, menos ou de asterisco.
  • Listas ordenadas, indicadas por um número inicial seguido por um ponto.
  • Texto em itálico, indicado por sublinhados ou asteriscos ao redor 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 inclusão de tag, consulte qualquer referência do Markdown, por exemplo, Guia de Markdown.

Como usar variáveis

Para adaptar o conteúdo da sua documentação, use variáveis no formato ${varname}. Quando a documentação for enviada com uma notificação, a string ${varname} será substituída pelo valor de varname. A captura de tela a seguir mostra a documentação incluída em uma notificação por e-mail, criada a partir do modelo de documentação especificado para uma política de alertas:

Documentação incluída no e-mail.

Para informações sobre como criar um modelo de documentação para uma política de alertas, consulte a etapa opcional de especificação da documentação a ser incluída nas notificações.

As variáveis a seguir ​​estão disponíveis para uso nos campos de documentação.

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.
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,4
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.

Os valores precisam ser prefixados com um dígito, uma letra, uma barra (/) ou um sinal de igual (=). Nenhum outro prefixo é permitido. Se um valor contiver um prefixo não compatível, ele não será informado.

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 KEY1,2.
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,3,4
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 Os rótulos de usuário em uma política só podem ser definidos usando a API Monitoring.
3 Para recuperar o valor do rótulo project_id em um recurso monitorado da política de alertas, use ${resource.project}.
4 Não é possível acessar rótulos de metadados de recursos definidos pelo usuário usando resource.label.KEY. Use metadata.user_label.KEY.

Valores null

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 (redução) entre séries como, 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, os rótulos não usados no agrupamento são descartados e, como resultado, são renderizados como null quando a variável é substituída pelo respectivo valor. Todos os rótulos são mantidos quando não há agregação de série cruzada.
  • 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.

Outras 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.

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. Isso pode ser usado para vincular a notificação a um usuário específico. Vamos supor 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 em questão como parte da notificação, essa linha aciona uma outra mensagem para o usuário backendoncall (por exemplo, de que a policy High CPU rate of change triggered an incident).

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.