1 Funções de macro

Visão geral

As funções de macro oferecem a capacidade de personalizar os valores das macros (por exemplo, encurtar ou extrair substrings específicas), tornando-os mais fáceis de trabalhar.

A sintaxe de uma função de macro é:

{macro.func(params)}

onde

• macro - a macro a ser personalizada;
• func - a função a ser aplicada (veja funções suportadas);
• params - uma lista de parâmetros da função separados por vírgula, que devem ser entre aspas duplas se:
  • começar com um espaço ou aspas duplas;
  • conter parênteses de fechamento ou uma vírgula.

Por exemplo:

{{TIME}.fmttime(format,time_shift)}
       {{ITEM.VALUE}.regsub(pattern, output)}
       {{$USERMACRO}.regsub(pattern, output)}
       {{#LLDMACRO}.regsub(pattern, output)}

As funções de macro são suportadas para:

• Macros internas
• Macros de usuário
• Macros de descoberta de baixo nível
• Macros de expressão

As funções de macro podem ser usadas em todos os locais que suportam as macros listadas. Isso se aplica, a menos que seja declarado explicitamente que apenas uma macro é esperada (por exemplo, ao configurar macros de host ou filtros de regras de descoberta de baixo nível).

Veja também: problemas conhecidos.

É suportada apenas uma função por macro; múltiplas funções de macro em cadeia não são suportadas.

Funções suportadas

As funções são listadas sem informações adicionais. Clique na função para ver os detalhes completos.

Detalhes da função

Os parâmetros opcionais da função são indicados por < >.

btoa

Codificando um valor de macro em codificação Base64. A codificação Base64 é um método para representar dados binários como texto, útil para armazenar e transmitir com segurança conteúdo binário por meio de protocolos baseados em texto.

Exemplo:

{{ITEM.VALUE}.btoa()} - codificará em Base64 um valor como "zabbix" em "emFiYml4"

Esta função é suportada desde o Zabbix 7.0.4.

fmtnum(digits)

Formatação de número para controlar o número de dígitos impressos após o ponto decimal.

Parâmetros:

• digits - o número de dígitos após o ponto decimal. Intervalo válido: 0-20. Zeros à direita não serão produzidos.

Exemplos:

{{ITEM.VALUE}.fmtnum(2)} - retornará "24.35" a partir de um valor recebido de "24.3483523"
       {{ITEM.VALUE}.fmtnum(0)} - retornará "24" a partir de um valor recebido de "24.3483523"

fmttime(format,<time_shift>)

Formatação de hora.
Observe que esta função pode ser usada com macros que resultam em um valor em um dos seguintes formatos de hora:

• hh:mm:ss
• yyyy-mm-ddThh:mm:ss[tz] (padrão ISO8601)
• timestamp UNIX

Parâmetros:

• format - string de formato obrigatória, compatível com a formatação da função strftime;
  
• time_shift (opcional) - o deslocamento de tempo aplicado ao horário antes da formatação; deve começar com -<N><time_unit> ou +<N><time_unit>, onde:
  
  • N - o número de unidades de tempo a adicionar ou subtrair;
  • time_unit - h (hora), d (dia), w (semana), M (mês) ou y (ano).

Comentários:

• O parâmetro time_shift suporta operações de tempo em múltiplos passos e pode incluir /<time_unit> para deslocar para o início da unidade de tempo (/d - meia-noite, /w - 1º dia da semana (segunda-feira), /M - 1º dia do mês, etc.). Exemplos: -1w - exatamente 7 dias atrás; -1w/w - segunda-feira da semana anterior; -1w/w+1d - terça-feira da semana anterior.
• As operações de tempo são calculadas da esquerda para a direita sem prioridades. Por exemplo, -1M/d+1h/w será interpretado como ((-1M/d)+1h)/w.

Exemplos:

{{TIME}.fmttime(%B)} - retornará "October" de um valor recebido de "1633098961"
       {{TIME}.fmttime(%d %B,-1M/M)} - retornará "1 September" de um valor recebido de "1633098961"

htmldecode

Decodificando um valor de macro de codificação HTML. Esta função é suportada desde o Zabbix 7.0.4.

Os seguintes caracteres são suportados:

Exemplo:

{{ITEM.VALUE}.htmldecode()} - irá decodificar um valor como "&lt;" em "<"

htmlencode

Codifica o valor de uma macro em codificação HTML. Esta função é suportada a partir do Zabbix 7.0.4.

Os seguintes caracteres são suportados:

Exemplo:

{{ITEM.VALUE}.htmlencode()} - irá codificar em HTML um caractere como "<" em "&lt;"

iregsub(pattern,output)

Extração de substring por correspondência de expressão regular (case-insensitive).

Parâmetros:

• pattern - a expressão regular a ser correspondida;
• output - as opções de saída. Os placeholders \1 - \9 são suportados para capturar grupos. \0 retorna o texto correspondente.

Comentários:

• Se não houver correspondência para a expressão regular, a função retorna uma string vazia.
• Se o padrão da função for uma expressão regular incorreta, a macro será avaliada como 'UNKNOWN' (exceto para macros de descoberta de baixo nível, caso em que a função será ignorada e a macro permanecerá não resolvida).
• Referências a grupos de captura inexistentes na string de substituição são substituídas por uma string vazia.

Exemplo:

{{ITEM.VALUE}.iregsub("fail|error|fault|problem","ERROR")} - será resolvido para "ERROR" se as substrings "fail", "error", "fault" ou "problem" forem recebidas (case-insensitive); retornará uma string vazia se não houver correspondência

lowercase

Transformação de todos os caracteres do valor da macro em minúsculas. Funciona com conjuntos de caracteres de byte único (como ASCII) e não suporta UTF-8. Esta função é suportada desde o Zabbix 7.0.4.

Exemplo:

{{ITEM.VALUE}.lowercase()} - irá transformar um valor como "Zabbix SERVER" em "zabbix server" (minúsculo)

regrepl(pattern,replacement,<pattern2>,<replacement2>,...)

Substituição de caractere/substring no valor da macro. Observe que esta função só é suportada com a biblioteca libpcre2. Se o Zabbix server/proxy foi compilado com libpcre, esta função retornará UNKNOWN. Esta função é suportada a partir do Zabbix 7.0.4.

Parâmetros:

• pattern - a expressão regular a ser correspondida;
• replacement - a string de substituição. Os placeholders \1 - \9 são suportados em strings de substituição para capturar grupos.

Comentários:

• Os padrões e substituições são processados sequencialmente, com cada par subsequente sendo aplicado de acordo com o resultado da substituição anterior;
• Referências a grupos de captura inexistentes na string de substituição são substituídas por uma string vazia.

Exemplos:

{{ITEM.VALUE}.regrepl("oldParam", "newParam")} - irá substituir "oldParam" por "newParam"
       {{ITEM.VALUE}.regrepl("([^a-z])","\\\1")} - todos os caracteres que não são letras serão escapados com uma barra invertida
       {$THRESHOLD:"{{#FSNAME}.regrepl(\"\\$\",\"\")}"} - irá remover uma barra invertida no final (por exemplo, para substituir "C:\" por "C:")
       {{ITEM.VALUE}.regrepl("_v1\.0", "_v2.0", "\(final\)", "")} - irá substituir várias partes no valor do item

regsub(pattern,output)

Extração de substring por correspondência de expressão regular (diferencia maiúsculas de minúsculas).

Parâmetros:

• pattern - a expressão regular a ser correspondida;
• output - as opções de saída. Os placeholders \1 - \9 são suportados para capturar grupos. \0 retorna o texto correspondente.

Comentários:

• Se não houver correspondência para a expressão regular, a função retorna uma string vazia.
• Se o padrão da função for uma expressão regular incorreta, a macro será avaliada como 'UNKNOWN' (exceto para macros de descoberta de baixo nível, caso em que a função será ignorada e a macro permanecerá não resolvida).
• Referências a grupos de captura inexistentes na string de substituição são substituídas por uma string vazia.

Exemplos:

{{ITEM.VALUE}.regsub("^([0-9]+)", Problem ID: \1)} - será resolvido como "Problem ID: 123" se um valor como "123 Log line" for recebido
       {{ITEM.VALUE}.regsub("fail|error|fault|problem","ERROR")} - será resolvido como "ERROR" se substrings "fail", "error", "fault" ou "problem" forem recebidas (diferencia maiúsculas de minúsculas); retornará uma string vazia se não houver correspondência

Veja mais exemplos.

tr(caracteres,substituição)

Transliteração de caracteres do valor da macro. Esta função é suportada desde o Zabbix 7.0.4.

• caracteres - o conjunto de caracteres a serem substituídos;
• substituição - o conjunto de caracteres de substituição correspondentes posicionalmente.

Exemplos:

{{ITEM.VALUE}.tr(abc, xyz)} - substituirá todas as ocorrências de "a" por "x", "b" por "y", "c" por "z"
       {{ITEM.VALUE}.tr(abc, xyzq)} - substituirá todas as ocorrências de "a" por "x", "b" por "y", "c" por "z" ("q" é ignorado)
       {{ITEM.VALUE}.tr(abcde, xyz)} - substituirá todas as ocorrências de "a" por "x", "b" por "y", "c" por "z", "d" por "z", "e" por "z" (ou seja, xyzzz)
       {{ITEM.VALUE}.tr("\\\'", "\/\"")} - substituirá todas as ocorrências de barra invertida por barra, aspas simples por aspas duplas
       {{ITEM.VALUE}.tr(A-Z,a-z)} - converterá todas as letras para minúsculas
       {{ITEM.VALUE}.tr(0-9a-z,*)} - substituirá todos os números e letras minúsculas por "*"
       {{ITEM.VALUE}.tr(0-9,ab)} - substituirá todas as ocorrências de 0 por "a" e substituirá todas as ocorrências de 1, 2, 3, 4, 5, 6, 7, 8 e 9 por "b"
       {{ITEM.VALUE}.tr(0-9abcA-L,*)} - substituirá todos os números, caracteres "abc" e o intervalo A-L por "*"
       {{ITEM.VALUE}.tr("\n","*")} - substituirá as ocorrências de fim de linha por *
       {{ITEM.VALUE}.tr("e", "\n")} - substituirá todos os "e" por fim de linha

Para incluir caracteres literais:

barra invertida - deve ser escapada como \\
       aspas simples - deve ser escapada como \'
       aspas duplas - deve ser escapada como \"

Sequências de escape suportadas com barra invertida:

\\\\ => \\ - barra invertida dupla para barra invertida simples
       \\a  => \a - alerta
       \\b  => \b - backspace
       \\f  => \f - form feed
       \\n  => \n - nova linha
       \\r  => \r - retorno
       \\t  => \t - tabulação horizontal
       \\v  => \v - tabulação vertical

uppercase

Transformação de todos os caracteres do valor da macro em maiúsculas. Funciona com conjuntos de caracteres de byte único (como ASCII) e não suporta UTF-8. Esta função é suportada desde o Zabbix 7.0.4.

Exemplo:

{{ITEM.VALUE}.uppercase()} - transformará um valor como "Zabbix Server" em "ZABBIX SERVER" (maiúsculas)

urldecode

Decodificando um valor de macro de uma codificação de URL. Esta função é suportada desde o Zabbix 7.0.4.

Exemplo:

{{ITEM.VALUE}.urldecode()} - irá decodificar um valor como "%2F" em "/"

urlencode

Codifica um valor de macro em codificação de URL. Esta função é suportada desde o Zabbix 7.0.4.

Exemplo:

{{ITEM.VALUE}.urlencode()} - irá codificar um caractere como "/" em "%2F"

Exemplos adicionais

A tabela abaixo mostra mais exemplos de uso de funções de macro.

Visualizando valores completos de items

Valores longos das macros {ITEM.VALUE} e {ITEM.LASTVALUE} resolvidas para items de texto/log são truncados para 20 caracteres em alguns locais do frontend. Para ver os valores completos dessas macros, você pode usar funções de macro, por exemplo:

{{ITEM.VALUE}.regsub("(.*)", \1)}
       {{ITEM.LASTVALUE}.regsub("(.*)", \1)}

Veja também: detalhes das macros {ITEM.VALUE} e {ITEM.LASTVALUE} macro details.