As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Modelos de rótulos e anotações **** Este tópico de documentação foi desenvolvido para espaços de trabalho do Grafana compatíveis com o **Grafana versão 10.x**. Para espaços de trabalho do Grafana compatíveis com o Grafana versão 9.x, consulte [Trabalhar no Grafana versão 9](using-grafana-v9.md). Para espaços de trabalho do Grafana compatíveis com o Grafana versão 8.x, consulte [Trabalhar no Grafana versão 8](using-grafana-v8.md). Você pode usar modelos para incluir dados de consultas e expressões em rótulos e anotações. Por exemplo, você pode querer definir o rótulo de severidade de um alerta com base no valor da consulta, ou usar o rótulo de instância da consulta em uma anotação de resumo para saber qual servidor está tendo alto uso da CPU. Todos os modelos devem ser escritos em [texto/modelo](https://pkg.go.dev/text/template). Independentemente de você estar criando um modelo de um rótulo ou uma anotação, você deve escrever cada modelo em linha dentro do rótulo ou anotação que você está criando. Isso significa que você não pode compartilhar modelos entre rótulos e anotações e, em vez disso, precisará copiar os modelos onde quiser usá-los. Cada modelo é avaliado sempre que a regra de alerta é avaliada, e é avaliado para cada alerta separadamente. Por exemplo, se a regra de alerta tiver uma anotação de resumo modelada, e a regra de alerta tiver dez alertas disparados, o modelo será executado dez vezes, uma vez para cada alerta. Você deve tentar evitar ao máximo realizar computações caras nos modelos. ## Exemplos Em vez de escrever um tutorial completo, text/template, the following examples attempt to show the most common use-cases we have seen for templates. You can use these examples verbatim, or adapt them as necessary for your use case. For more information about how to write text/template consulte a documentação de [texto/modelo](https://pkg.go.dev/text/template). **Imprimir todos os rótulos, separados por vírgula** Para imprimir todos os rótulos, separados por vírgula, imprima a variável `$labels`: ``` {{ $labels }} ``` Por exemplo, para um alerta com os rótulos `alertname=High CPU usage`, `grafana_folder=CPU alerts` e `instance=server1`, vai imprimir: ``` alertname=High CPU usage, grafana_folder=CPU alerts, instance=server1 ``` **nota** Se você estiver usando condições clássicas, `$labels` não conterá nenhum rótulo da consulta. Consulte [a variável \$1labels](#v10-alerting-overview-labels-templating-the-labels-variable) para obter mais informações. **Imprimir todos os rótulos, um por linha** Para imprimir todas as etiquetas, uma por linha, use `range` a para iterar sobre cada key/value par e imprimi-las individualmente. Aqui, `$k` refere-se ao nome e `$v` refere-se ao valor do rótulo atual: ``` {{ range $k, $v := $labels -}} {{ $k }}={{ $v }} {{ end }} ``` Por exemplo, para um alerta com os rótulos `alertname=High CPU usage`, `grafana_folder=CPU alerts` e `instance=server1`, vai imprimir: ``` alertname=High CPU usage grafana_folder=CPU alerts instance=server1 ``` **nota** Se você estiver usando condições clássicas, `$labels` não conterá nenhum rótulo da consulta. Consulte [a variável \$1labels](#v10-alerting-overview-labels-templating-the-labels-variable) para obter mais informações. **Imprimir um rótulo individual** Para imprimir um rótulo individual, use a função `index` com a variável `$labels`: ``` The host {{ index $labels "instance" }} has exceeded 80% CPU usage for the last 5 minutes ``` Por exemplo, para um alerta com o rótulo `instance=server1`, vai imprimir: ``` The host server1 has exceeded 80% CPU usage for the last 5 minutes ``` **nota** Se você estiver usando condições clássicas, `$labels` não conterá nenhum rótulo da consulta. Consulte [a variável \$1labels](#v10-alerting-overview-labels-templating-the-labels-variable) para obter mais informações. **Imprimir o valor de uma consulta** Para imprimir o valor de uma consulta instantânea, você pode imprimir seu ID de referência usando a função `index` e a variável `$values`: ``` {{ index $values "A" }} ``` Por exemplo, uma consulta instantânea específica que retorna o valor 81,2345, vai imprimir: ``` 81.2345 ``` Para imprimir o valor de uma consulta de intervalo, você deve primeiro reduzi-la de uma série temporal para um vetor instantâneo com uma expressão de redução. Em seguida, você pode imprimir o resultado da expressão de redução usando seu ID de referência. Por exemplo, se a expressão de redução pegar a média de A e tiver o ID de referência B, você vai escrever: ``` {{ index $values "B" }} ``` **Imprimir o valor humanizado de uma consulta** Para imprimir o valor humanizado de uma consulta instantânea, use a função `humanize`: ``` {{ humanize (index $values "A").Value }} ``` Por exemplo, uma consulta instantânea específica que retorna o valor 81,2345, vai imprimir: ``` 81.234 ``` Para imprimir o valor humanizado de uma consulta de intervalo, você deve primeiro reduzi-la de uma série temporal para um vetor instantâneo com uma expressão de redução. Em seguida, você pode imprimir o resultado da expressão de redução usando seu ID de referência. Por exemplo, se a expressão de redução pegar a média de A e tiver o ID de referência B, você vai escrever: ``` {{ humanize (index $values "B").Value }} ``` **Imprimir o valor de uma consulta como uma porcentagem** Para imprimir o valor de uma consulta instantânea como porcentagem, use a função `humanizePercentage`: ``` {{ humanizePercentage (index $values "A").Value }} ``` Essa função espera que o valor seja um número decimal entre 0 e 1. Se, em vez disso, o valor for um número decimal entre 0 e 100, você poderá dividi-lo por 100 na consulta ou usando uma expressão matemática. Se a consulta for uma consulta de intervalo, você deverá primeiro reduzi-la de uma série temporal para um vetor instantâneo com uma expressão de redução. **Definir uma severidade do valor de uma consulta** Para definir um rótulo de severidade do valor de uma consulta, use uma instrução if e a função de comparação maior que. Certifique-se de usar decimais (`80.0`,, `50.0``0.0`, etc) ao fazer comparações, `$values` pois não text/template suporta coerção de tipo. Você pode encontrar uma lista de todas as funções de comparação compatíveis [aqui](https://pkg.go.dev/text/template#hdr-Functions). ``` {{ if (gt $values.A.Value 80.0) -}} high {{ else if (gt $values.A.Value 50.0) -}} medium {{ else -}} low {{- end }} ``` **Imprimir todos os rótulos de uma condição clássica** Você não poderá usar `$labels` para imprimir rótulos da consulta se estiver usando condições clássicas, e deverá usar `$values` em vez disso. A razão para isso é que as condições clássicas descartam esses rótulos para impor um comportamento unidimensional (no máximo um alerta por regra de alerta). Se as condições clássicas não descartassem esses rótulos, as consultas que retornassem várias séries temporais fariam com que os alertas oscilassem entre o disparo e a resolução constantemente, pois os rótulos mudariam toda vez que a regra de alerta fosse avaliada. Em vez disso, a variável `$values` contém os valores reduzidos de todas as séries temporais para todas as condições que estão disparando. Por exemplo, se você tiver uma regra de alerta com uma consulta A que retorna duas séries temporais e uma condição B clássica com duas condições, então `$values` conterá `B0`, `B1`, `B2` e `B3`. Se a condição clássica B tiver apenas uma condição, então `$values` conterá apenas `B0` e `B1`. Para imprimir todos os rótulos de todas as séries temporais de disparo, use o modelo a seguir (certifique-se de substituir `B` na expressão regular pelo ID de referência da condição clássica, caso seja diferente): ``` {{ range $k, $v := $values -}} {{ if (match "B[0-9]+" $k) -}} {{ $k }}: {{ $v.Labels }}{{ end }} {{ end }} ``` Por exemplo, uma condição clássica para duas séries temporais que excedam uma única condição, vai imprimir: ``` B0: instance=server1 B1: instance=server2 ``` Se a condição clássica tiver duas ou mais condições e uma série temporal exceder várias condições ao mesmo tempo, então os rótulos serão duplicados para cada condição excedida: ``` B0: instance=server1 B1: instance=server2 B2: instance=server1 B3: instance=server2 ``` Se precisar imprimir rótulos exclusivos, considere alterar as regras de alerta de unidimensionais para multidimensionais. Você pode fazer isso substituindo a condição clássica por expressões de redução e matemáticas. **Imprimir todos os valores de uma condição clássica** Para imprimir todos os valores de uma condição clássica, pegue o exemplo anterior e substitua `$v.Labels` por `$v.Value`: ``` {{ range $k, $v := $values -}} {{ if (match "B[0-9]+" $k) -}} {{ $k }}: {{ $v.Value }}{{ end }} {{ end }} ``` Por exemplo, uma condição clássica para duas séries temporais que excedam uma única condição, vai imprimir: ``` B0: 81.2345 B1: 84.5678 ``` Se a condição clássica tiver duas ou mais condições e uma série temporal exceder várias condições ao mesmo tempo, então `$values` conterá os valores de todas as condições: ``` B0: 81.2345 B1: 92.3456 B2: 84.5678 B3: 95.6789 ``` ## Variáveis As variáveis a seguir estão disponíveis para você ao criar modelos de rótulos e anotações: ### A variável de rótulos A variável `$labels` contém todos os rótulos da consulta. Por exemplo, suponha que você tenha uma consulta que retorne o uso da CPU de todos os servidores e tenha uma regra de alerta que é disparada quando algum dos servidores excede 80% do uso da CPU nos últimos cinco minutos. Você deseja adicionar uma anotação de resumo ao alerta que informa qual servidor está enfrentando alto uso da CPU. Com a variável `$labels`, você pode escrever um modelo que imprima uma frase legível por humanos, como: ``` CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes ``` **nota** Se você estiver usando uma condição clássica, `$labels` não conterá nenhum rótulo da consulta. As condições clássicas descartam esses rótulos para impor um comportamento unidimensional (no máximo um alerta por regra de alerta). Caso queira usar rótulos da consulta no modelo, siga o exemplo anterior de *Imprimir todos os rótulos de uma condição clássica*. ### O valor da variável A variável `$value` é uma string que contém os rótulos e valores de todas as consultas instantâneas, expressões de limite, redução e matemáticas e condições clássicas na regra de alerta. Ela não contém os resultados das consultas de intervalo, pois estas podem retornar de 10 a 10 mil linhas ou métricas. Se isso acontecesse, para consultas especialmente grandes, um único alerta poderia usar 10s MBs de memória e o Grafana ficaria sem memória muito rapidamente. Para imprimir a variável `$value` no resumo, você deve escrever algo assim: ``` CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes: {{ $value }} ``` E ficaria semelhante ao abaixo: ``` CPU usage for instance1 has exceeded 80% for the last 5 minutes: [ var='A' labels={instance=instance1} value=81.234 ] ``` Aqui, `var='A'` refere-se à consulta instantânea com o ID de referência A, `labels={instance=instance1}` refere-se aos rótulos e `value=81.234` refere-se ao uso médio da CPU nos últimos cinco minutos. Se você quiser imprimir apenas parte da string em vez da string completa, use a variável `$values`. Ela contém as mesmas informações que `$value`, mas em uma tabela estruturada, e é muito mais fácil de usar do que escrever uma expressão regular para corresponder apenas ao texto desejado. ### A variável de valores A `$values` variável é uma tabela contendo os rótulos e valores de ponto flutuante de todas as consultas e expressões instantâneas, indexadas por sua Ref. IDs Para imprimir o valor da consulta instantânea com o ID de referência A: ``` CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes: {{ index $values "A" }} ``` Por exemplo, um alerta específico com os rótulos `instance=server1` e uma consulta instantânea com o valor `81.2345`, vai imprimir: ``` CPU usage for instance1 has exceeded 80% for the last 5 minutes: 81.2345 ``` Se a consulta no ID de referência A for uma consulta de intervalo em vez de uma consulta instantânea, adicione uma expressão de redução com o ID de referência B e substitua `(index $values "A")` por `(index $values "B")`: ``` CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes: {{ index $values "B" }} ``` ## Funções As seguintes funções estão disponíveis para você ao criar modelos de rótulos e anotações: **args** A função `args` converte uma lista de objetos em um mapa com as chaves arg0, arg1 etc. O objetivo é permitir que vários argumentos sejam transmitidos para os modelos. ``` {{define "x"}}{{.arg0}} {{.arg1}}{{end}}{{template "x" (args 1 "2")}} ``` ``` 1 2 ``` **externalURL** A função `externalURL` retorna o URL externo do servidor Grafana. ``` {{ externalURL }} ``` ``` https://example.com/grafana ``` **graphLink** A função `graphLink` retorna o caminho para a visualização de grafo em [Explore na versão 10 do Grafana](v10-explore.md) para a expressão e a fonte de dados fornecidas. ``` {{ graphLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }} ``` ``` /explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":false,"range":true}] ``` **humanize** A função `humanize` humaniza os números decimais. ``` {{ humanize 1000.0 }} ``` ``` 1k ``` **humanize1024** A `humanize1024` funciona de forma semelhante a `humanize`, mas usa 1024 como base em vez de 1000. ``` {{ humanize1024 1024.0 }} ``` ``` 1ki ``` **humanizeDuration** A função `humanizeDuration` humaniza a duração em segundos. ``` {{ humanizeDuration 60.0 }} ``` ``` 1m 0s ``` **humanizePercentage** A função `humanizePercentage` humaniza um valor de proporção para uma porcentagem. ``` {{ humanizePercentage 0.2 }} ``` ``` 20% ``` **humanizeTimestamp** A `humanizeTimestamp` função humaniza um carimbo de data e hora do Unix. ``` {{ humanizeTimestamp 1577836800.0 }} ``` ``` 2020-01-01 00:00:00 +0000 UTC ``` **match** A função `match` combina o texto com um padrão de expressão regular. ``` {{ match "a.*" "abc" }} ``` ``` true ``` **pathPrefix** A função `pathPrefix` retorna o caminho do servidor Grafana. ``` {{ pathPrefix }} ``` ``` /grafana ``` **tableLink** A função `tableLink` retorna o caminho para a visualização tabular em [Explore na versão 10 do Grafana](v10-explore.md) para a expressão e fonte de dados fornecidas. ``` {{ tableLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }} ``` ``` /explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":true,"range":false}] ``` **title** A função `title` coloca em maiúscula o primeiro caractere de cada palavra. ``` {{ title "hello, world!" }} ``` ``` Hello, World! ``` **toLower** A função `toLower` retorna todo o texto em letras minúsculas. ``` {{ toLower "Hello, world!" }} ``` ``` hello, world! ``` **toUpper** A função `toUpper` retorna todo o texto em maiúsculas. ``` {{ toUpper "Hello, world!" }} ``` ``` HELLO, WORLD! ``` **reReplaceAll** A função `reReplaceAll` substitui o texto correspondente à expressão regular. ``` {{ reReplaceAll "localhost:(.*)" "example.com:$1" "localhost:8080" }} ``` ``` example.com:8080 ```