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 9.x**. Para espaços de trabalho do Grafana compatíveis com o Grafana versão 10.x, consulte [Trabalhar no Grafana versão 10](using-grafana-v10.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). No Grafana, você cria modelos de rótulos e anotações da mesma forma como no Prometheus. Se você já usou o Prometheus antes, então deve estar familiarizado com as variáveis `$labels` e `$value`, que contêm os rótulos e o valor do alerta. Você pode usar as mesmas variáveis no Grafana, mesmo que o alerta não use uma fonte de dados Prometheus. Se você nunca usou o Prometheus antes, não se preocupe, pois cada uma dessas variáveis e como modelá-las serão explicadas conforme você avançar nesta página. ## Linguagem de modelos do Go Os modelos para rótulos e anotações são escritos na linguagem de modelos do Go, [texto/modelo](https://pkg.go.dev/text/template). **Tags de abertura e fechamento** Em texto/modelo, os modelos começam com `{{` e terminam com `}}`, independentemente de o modelo imprimir uma variável ou executar estruturas de controle, como instruções if. Isso é diferente de outras linguagens de modelos, como Jinja, em que a impressão de uma variável usa `{{` e `}}` e as estruturas de controle usam `{%` e `%}`. **Print (Imprimir)** Para imprimir o valor de algo, use `{{` e `}}`. Você pode imprimir o resultado de uma função ou valor de uma variável. Por exemplo, para imprimir a variável `$labels`, você deve escrever o seguinte: ``` {{ $labels }} ``` **Iterar em rótulos** Para iterar em cada rótulo em `$labels`, você pode usar um `range`. Aqui, `$k` refere-se ao nome e `$v` refere-se ao valor do rótulo atual. Por exemplo, se a consulta retornasse um rótulo `instance=test`, então `$k` seria `instance` e `$v`seria `test`. ``` {{ range $k, $v := $labels }} {{ $k }}={{ $v }} {{ end }} ``` ## Os rótulos, valores e variáveis de valores **A variável de rótulos** A variável `$labels` contém os rótulos da consulta. Por exemplo, uma consulta que verifica se uma instância está inativa pode retornar um rótulo de instância com o nome da instância que está inativa. Por exemplo, suponha que você tenha uma regra de alerta que é disparada quando uma das instâncias fica inativa por mais de cinco minutos. Você deseja adicionar um resumo ao alerta que informa qual instância está inativa. Com a variável `$labels`, você pode criar um resumo que imprima o rótulo da instância no resumo: ``` Instance {{ $labels.instance }} has been down for more than 5 minutes ``` **Rótulos com pontos** Se o rótulo que você deseja imprimir contiver um ponto (ponto final) em seu nome, usar o mesmo ponto no modelo não funcionará: ``` Instance {{ $labels.instance.name }} has been down for more than 5 minutes ``` Isso ocorre porque o modelo está tentando usar um campo não existente denominado `name` em `$labels.instance`. Em vez disso, você deve usar a função `index`, que imprime o rótulo `instance.name` na variável `$labels`: ``` Instance {{ index $labels "instance.name" }} has been down for more than 5 minutes ``` **O valor da variável** A variável `$value` funciona de forma diferente do Prometheus. No `$value` do Prometheus, há um número de ponto flutuante que contém o valor da expressão, mas no Grafana é uma string que contém os rótulos e valores de todas as expressões de limite, de redução, matemáticas e de condições clássicas dessa regra de alerta. Ela não contém os resultados das consultas, pois podem retornar de 10 a 10 mil linhas ou métricas. Se você fosse usar a variável `$value` no resumo de um alerta: ``` {{ $labels.service }} has over 5% of responses with 5xx errors: {{ $value }}) ``` O resumo pode ficar como abaixo: ``` api has an over 5% of responses with 5xx errors: [ var='B' labels={service=api} value=6.789 ] ``` Aqui, `var='B'` refere-se à expressão com o RefID B. No Grafana, todas as consultas e expressões são identificadas por um RefID que identifica cada consulta e expressão em uma regra de alerta. Da mesma forma, `labels={service=api}` refere-se aos rótulos e `value=6.789` refere-se ao valor. Você deve ter observado que não há nenhum RefID A. Isso ocorre porque, na maioria das regras de alerta, o RefID A refere-se a uma consulta, e como as consultas podem retornar muitas linhas ou séries temporais, elas não estão incluídas em `$value`. **A variável de valores** Se a variável `$value` contiver mais informações do que você precisa, é possível imprimir os rótulos e o valor de expressões individuais usando `$values`. Ao contrário de `$value`, a variável `$values` é uma tabela de objetos que contêm os rótulos e valores de ponto flutuante de cada expressão, indexados por seu RefID. Se você imprimir o valor da expressão com o RefID `B` no resumo do alerta: ``` {{ $labels.service }} has over 5% of responses with 5xx errors: {{ $values.B }}% ``` O resumo conterá apenas o valor: ``` api has an over 5% of responses with 5xx errors: 6.789% ``` No entanto, enquanto `{{ $values.B }}` imprime o número 6.789, na verdade é uma string, pois você estar imprimindo o objeto que contém os rótulos e o valor do RefID B, não o valor de ponto flutuante de B. Para usar o valor de ponto flutuante do RefID B, você deve usar o campo `Value` de `$values.B`. Se você fosse humanizar o valor do ponto flutuante no resumo de um alerta: ``` {{ $labels.service }} has over 5% of responses with 5xx errors: {{ humanize $values.B.Value }}% ``` **Nenhum dado, erros de runtime e tempos limite** Se a consulta na regra de alerta não retornar nenhum dado ou falhar devido a um erro na fonte de dados ou ao tempo limite, todas as expressões de limite, redução e matemáticas que usem essa consulta também não retornarão nenhum dado ou retornarão um erro. Quando isso acontecer, essa expressão estará ausente de `$values`. É uma boa prática verificar se um RefID está presente antes de usá-lo, caso contrário, o modelo será pausado se sua consulta não retornar nenhum dado ou retornar um erro. É possível fazer isso usando uma instrução if: ``` {{ if $values.B }}{{ $labels.service }} has over 5% of responses with 5xx errors: {{ humanizePercentage $values.B.Value }}{{ end }} ``` ## Condições clássicas Se a regra usar condições clássicas em vez das expressões de limite, redução e matemáticas, a variável `$values` será indexada pelo ID de referência e pela posição da condição na condição clássica. Por exemplo, se você tiver uma condição clássica com o RefID B que contém duas condições, então `$values` conterá duas condições `B0` e `B1`. ``` The first condition is {{ $values.B0 }}, and the second condition is {{ $values.B1 }} ``` ## Funções As seguintes funções também estão disponíveis ao expandir anotações e rótulos: **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. **Exemplo** ``` {{define "x"}}{{.arg0}} {{.arg1}}{{end}}{{template "x" (args 1 "2")}} ``` ``` 1 2 ``` **externalURL** A função `externalURL` retorna o URL externo do servidor Grafana, conforme configurado nos arquivos ini. **Exemplo** ``` {{ externalURL }} ``` ``` https://example.com/grafana ``` **graphLink** A função `graphLink` retorna o caminho para a visualização de grafo em [Explore na versão 9 do Grafana](v9-explore.md) para a expressão e a fonte de dados fornecidas. **Exemplo** ``` {{ 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. **Exemplo** ``` {{ humanize 1000.0 }} ``` ``` 1k ``` **humanize1024** A `humanize1024` funciona de forma semelhante a `humanize`, mas usa 1024 como base em vez de 1000. **Exemplo** ``` {{ humanize1024 1024.0 }} ``` ``` 1ki ``` **humanizeDuration** A função `humanizeDuration` humaniza a duração em segundos. **Exemplo** ``` {{ humanizeDuration 60.0 }} ``` ``` 1m 0s ``` **humanizePercentage** A função `humanizePercentage` humaniza um valor de proporção para uma porcentagem. **Exemplo** ``` {{ humanizePercentage 0.2 }} ``` ``` 20% ``` **humanizeTimestamp** A `humanizeTimestamp` função humaniza um carimbo de data e hora do Unix. **Exemplo** ``` {{ 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. **Exemplo** ``` {{ match "a.*" "abc" }} ``` ``` true ``` **pathPrefix** A função `pathPrefix` retorna o caminho do servidor Grafana, conforme configurado nos arquivos ini. **Exemplo** ``` {{ pathPrefix }} ``` ``` /grafana ``` **tableLink** A função `tableLink` retorna o caminho para a visualização tabular em [Explore na versão 9 do Grafana](v9-explore.md) para a expressão e fonte de dados fornecidas. **Exemplo** ``` {{ 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. **Exemplo** ``` {{ title "hello, world!" }} ``` ``` Hello, World! ``` **toLower** A função `toLower` retorna todo o texto em letras minúsculas. **Exemplo** ``` {{ toLower "Hello, world!" }} ``` ``` hello, world! ``` **toUpper** A função `toUpper` retorna todo o texto em maiúsculas. **Exemplo** ``` {{ toUpper "Hello, world!" }} ``` ``` HELLO, WORLD! ``` **reReplaceAll** A função `reReplaceAll` substitui o texto correspondente à expressão regular. **Exemplo** ``` {{ reReplaceAll "localhost:(.*)" "example.com:$1" "localhost:8080" }} ``` ``` example.com:8080 ```