2 Pré-processamento de valor de item

Visão geral

O pré-processamento permite aplicar transformações aos valores de item recebidos antes de salvá-los no banco de dados. Essas transformações/etapas de pré-processamento são executadas pelo Zabbix server ou proxy (se os itens forem monitorados por proxy).

Esse recurso oferece suporte a vários casos de uso, como:

• converter bytes em bits (por exemplo, multiplicando os valores de tráfego de rede por "8");
• calcular estatísticas por segundo para valores que aumentam incrementalmente;
• aplicar expressões regulares para extrair ou modificar valores;
• executar scripts personalizados nos valores;
• descartar valores inalterados para otimizar o armazenamento no banco de dados.

Uma ou mais etapas de pré-processamento podem ser configuradas para um item. Essas etapas são executadas na ordem em que são configuradas.

Todos os valores passados para o pré-processamento são inicialmente tratados como strings. A conversão para o tipo de valor desejado (conforme definido na configuração do item) é realizada ao final do pipeline de pré-processamento. No entanto, etapas específicas de pré-processamento podem acionar conversões mais cedo, se necessário. Para informações técnicas detalhadas, consulte Detalhes do pré-processamento.

Para garantir que sua configuração de pré-processamento funcione conforme o esperado, você pode testá-la.

Veja também: Exemplos de pré-processamento

Configuração

As etapas de pré-processamento são definidas na aba Pré-processamento do formulário de configuração do item.

Clique em Adicionar para selecionar uma transformação compatível.

O campo Tipo de informação é exibido na parte inferior da aba quando pelo menos uma etapa de pré-processamento é definida. Se necessário, é possível alterar o tipo de informação sem sair da aba Pré-processamento. Consulte Criando um item para obter uma descrição detalhada dos parâmetros.

Transformações compatíveis

Todas as transformações compatíveis estão listadas abaixo.
Clique no nome da transformação para ver todos os detalhes sobre ela.

Se a caixa de seleção Personalizado em caso de falha estiver habilitada para a transformação selecionada, você poderá marcá-la e especificar opções personalizadas de tratamento de erros: Descartar valor (descartar o valor), Definir valor como (definir um valor especificado) ou Definir erro como (definir uma mensagem de erro especificada).
Se uma etapa de pré-processamento falhar, o item não se tornará não compatível quando a opção Descartar valor ou Definir valor como estiver selecionada.

Observe que, para as etapas de pré-processamento Alteração e Limitação, o Zabbix precisa memorizar o último valor para calcular/comparar o novo valor conforme necessário.
Esses valores anteriores são tratados pelo gerenciador de pré-processamento.
Se o Zabbix server ou o proxy for reiniciado, ou se houver qualquer alteração nas etapas de pré-processamento, o último valor do item correspondente será redefinido, resultando no seguinte:

• para as etapas Alteração simples e Alteração por segundo: o próximo valor será ignorado porque não há um valor anterior a partir do qual calcular a alteração;
• para as etapas Descartar se inalterado e Descartar se inalterado com heartbeat: o próximo valor nunca será descartado, mesmo que isso devesse ocorrer de acordo com as regras de descarte.

Expressão regular

Corresponde o valor à expressão regular e substitui-o pela saída necessária.

Parâmetros:

• pattern - a expressão regular;
  
• output - o template de formatação da saída. Uma sequência de escape \N (onde N=1…9) é substituída pelo N-ésimo grupo correspondente. Uma sequência de escape \0 é substituída pelo texto correspondente.

Comentários:

• Uma falha ao corresponder o valor de entrada fará com que o item fique sem suporte;
  
• A expressão regular permite a extração de no máximo 10 grupos capturados com a sequência \N;
  
• Consulte a seção expressões regulares para ver alguns exemplos existentes.

Substituir

Encontre a string de pesquisa e substitua por outra (ou nada).

Parâmetros:

• string de pesquisa - a string a ser encontrada e substituída, diferencia maiúsculas de minúsculas (obrigatório);
  
• substituição - a string para substituir a string de pesquisa. A string de substituição também pode estar vazia, permitindo efetivamente excluir a string de pesquisa quando encontrada.

Comentários:

• Todas as ocorrências da string de pesquisa serão substituídas;
• É possível usar sequências de escape para pesquisar ou substituir quebras de linha, retorno de carro, tabulações e espaços "\n \r \t \s"; a barra invertida pode ser escapada como "\\" e as sequências de escape podem ser escapadas como "\\n";
• O escape de quebras de linha, retorno de carro e tabulações é feito automaticamente durante a descoberta de baixo nível.

Trim

Remove os caracteres especificados do início e do final do valor.

Remover à direita

Remove os caracteres especificados do final do valor.

Remover à esquerda

Remove os caracteres especificados do início do valor.

XML XPath

Extraia um valor ou fragmento de dados XML usando a funcionalidade XPath.

Comentários:

• Para que esta opção funcione, o Zabbix server (ou o Zabbix proxy) deve ser compilado com suporte à libxml;
  
• Namespaces não são compatíveis.

Exemplos:

number(/document/item/value) #extrairá '10' de <document><item><value>10</value></item></document>
number(/document/item/@attribute) #extrairá '10' de <document><item attribute="10"></item></document>
/document/item #extrairá '<item><value>10</value></item>' de <document><item><value>10</value></item></document>

JSON Path

Extraia um valor ou fragmento de dados JSON usando a funcionalidade JSONPath.

CSV para JSON

Converta dados de arquivos CSV para o formato JSON.

Para mais informações, consulte: pré-processamento de CSV para JSON.

XML para JSON

Converta dados no formato XML para JSON.

Para obter mais informações, consulte: Regras de serialização.

Valor da consulta SNMP

Extraia o valor pelo OID/nome MIB especificado e aplique as opções de formatação:

• Inalterado - retorna a sequência hexadecimal como uma sequência hexadecimal sem escape (observe que as dicas de exibição ainda são aplicadas);
  
• UTF-8 de STRING hexadecimal - converte a sequência hexadecimal em uma sequência UTF-8;
  
• MAC de STRING hexadecimal - valida a sequência hexadecimal como um endereço MAC e retorna uma sequência de endereço MAC adequada (em que ' ' é substituído por ':');
  
• Inteiro de BITS - converte os primeiros 8 bytes de uma sequência de bits expressa como uma sequência de caracteres hexadecimais (por exemplo, "1A 2B 3C 4D") em um inteiro sem sinal de 64 bits. Em sequências de bits com mais de 8 bytes, os bytes subsequentes serão ignorados.

SNMP walk para JSON

Converta valores SNMP em JSON.

Especifique um nome de campo no JSON e o caminho OID SNMP correspondente. Os valores dos campos serão preenchidos com os valores do caminho OID SNMP especificado.

Comentários:

• Estão disponíveis opções de formatação de valores semelhantes às da etapa Valor do SNMP walk;
  
• Você pode usar esta etapa de pré-processamento para descoberta de OID SNMP.

Obter valor SNMP

Aplique opções de formatação ao valor obtido via SNMP:

• UTF-8 de Hex-STRING - converte uma sequência hexadecimal em uma sequência UTF-8;
  
• MAC de Hex-STRING - valida a sequência hexadecimal como um endereço MAC e retorna uma sequência de endereço MAC adequada (em que ' ' é substituído por ':');
  
• Inteiro de BITS - converte os primeiros 8 bytes de uma sequência de bits expressa como uma sequência de caracteres hexadecimais (por exemplo, "1A 2B 3C 4D") em um inteiro sem sinal de 64 bits. Em sequências de bits com mais de 8 bytes, os bytes subsequentes serão ignorados.

Multiplicador personalizado

Multiplica o valor pelo valor inteiro ou de ponto flutuante especificado.

Comentários:

• Use esta opção para converter valores recebidos em KB, MBps etc. para B, Bps. Caso contrário, o Zabbix não poderá definir corretamente os prefixos (K, M, G etc.).
  
• Observe que, se o tipo de informação do item for Numérico (sem sinal), os valores recebidos com uma parte fracionária serão truncados (ou seja, '0.9' se tornará '0') antes que o multiplicador personalizado seja aplicado;
  
• Se você usar um multiplicador personalizado ou armazenar o valor como Alteração por segundo para itens cujo tipo de informação esteja definido como Numérico (sem sinal) e o valor calculado resultante for, na verdade, um número de ponto flutuante, o valor calculado ainda será aceito como correto, com a parte decimal sendo truncada e o valor armazenado como um inteiro;
  
• Compatível com: notação científica, por exemplo, 1e+70; macros de usuário e macros LLD; strings que incluem macros, por exemplo, {#MACRO}e+10, {$MACRO1}e+{$MACRO2}. As macros devem ser resolvidas para um número inteiro ou de ponto flutuante.

Alteração simples

Calcule a diferença entre o valor atual e o anterior.

Comentários:

• Esta etapa pode ser útil para medir um valor que cresce constantemente;
  
• Avaliado como value-prev_value, em que value é o valor atual; prev_value é o valor recebido anteriormente;
  
• É permitida apenas uma operação de alteração por item ("Alteração simples" ou "Alteração por segundo");
• Se o valor atual for menor que o valor anterior, o Zabbix descarta essa diferença (não armazena nada) e aguarda outro valor.

Alteração por segundo

Calcule a velocidade de alteração do valor (diferença entre o valor atual e o anterior) por segundo.

Comentários:

• Esta etapa é útil para calcular a velocidade por segundo de um valor que cresce constantemente;
  
• Como esse cálculo pode produzir números de ponto flutuante, é recomendável definir o 'Tipo de informação' como Numérico (ponto flutuante), mesmo que os valores brutos recebidos sejam inteiros. Isso é especialmente relevante para números pequenos, nos quais a parte decimal é importante. Se os valores de ponto flutuante forem grandes e puderem exceder o comprimento do campo 'float', fazendo com que o valor inteiro seja perdido, é recomendável usar Numérico (sem sinal) e, assim, remover apenas a parte decimal.
  
• Avaliado como (value-prev_value)/(time-prev_time), em que value - o valor atual; prev_value - o valor recebido anteriormente; time - o timestamp atual; prev_time - o timestamp do valor anterior;
  
• Apenas uma operação de alteração por item ("Alteração simples" ou "Alteração por segundo") é permitida;
• Se o valor atual for menor que o valor anterior, o Zabbix descartará essa diferença (não armazenará nada) e aguardará outro valor. Isso ajuda a funcionar corretamente com, por exemplo, um contador SNMP de 32 bits que retorna ao início após atingir o limite (overflow).

Booleano para decimal

Converte o valor do formato booleano para decimal.

Comentários:

• A representação textual é convertida em 0 ou 1. Assim, 'TRUE' é armazenado como 1 e 'FALSE' é armazenado como 0. Todos os valores são correspondidos sem distinção entre maiúsculas e minúsculas. Os valores reconhecidos atualmente são, para TRUE - true, t, yes, y, on, up, running, enabled, available, ok, master; para FALSE - false, f, no, n, off, down, unused, disabled, unavailable, err, slave. Além disso, qualquer valor numérico diferente de zero é considerado TRUE, e zero é considerado FALSE.

Octal para decimal

Converte o valor do formato octal para decimal.

Hexadecimal para decimal

Converte o valor do formato hexadecimal para decimal.

JavaScript

Digite o código JavaScript no editor modal que é aberto ao clicar no campo de parâmetro ou no ícone de lápis ao lado dele.

Comentários:

• O comprimento do JavaScript disponível depende do banco de dados usado;
  
• Para mais informações, consulte: Pré-processamento em Javascript.

No intervalo

Defina um intervalo no qual um valor deve estar, especificando os valores mínimo/máximo (inclusive).

Comentários:

• Valores numéricos são aceitos (incluindo qualquer número de dígitos, parte decimal opcional e parte exponencial opcional, valores negativos);
  
• O valor mínimo deve ser menor que o máximo;
  
• Deve existir pelo menos um valor;
  
• Macros de usuário e macros de descoberta de baixo nível podem ser usadas.

Corresponde à expressão regular

Especifique uma expressão regular à qual um valor deve corresponder.

Não corresponde à expressão regular

Especifique uma expressão regular à qual um valor não deve corresponder.

Verificar se há um erro no JSON

Verifique se há uma mensagem de erro no nível da aplicação localizada no JSONPath. Interrompa o processamento se a operação for bem-sucedida e a mensagem não estiver vazia; caso contrário, continue o processamento com o valor que estava disponível antes desta etapa de pré-processamento.

Comentários:

• Esses erros de serviços externos são relatados ao usuário como estão, sem adicionar informações sobre a etapa de pré-processamento;
  
• Nenhum erro será relatado caso não seja possível analisar um JSON inválido.

Verificar se há um erro no XML

Verifique se há uma mensagem de erro no nível da aplicação localizada no XPath.
Interrompa o processamento se a verificação for bem-sucedida e a mensagem não estiver vazia; caso contrário, continue o processamento com o valor que estava disponível antes desta etapa de pré-processamento.

Comentários:

• Esses erros de serviços externos são relatados ao usuário como estão, sem adicionar informações sobre a etapa de pré-processamento;
  
• Nenhum erro será relatado caso não seja possível analisar um XML inválido.

Verificar erro usando uma expressão regular

Verifique uma mensagem de erro no nível da aplicação usando uma expressão regular. Interrompa o processamento se for bem-sucedido e a mensagem não estiver vazia; caso contrário, continue o processamento com o valor que estava presente antes desta etapa de pré-processamento.

Parâmetros:

• pattern - a expressão regular;
  
• output - o template de formatação da saída. Uma sequência de escape \N (onde N=1…9) é substituída pelo Nº grupo correspondente. Uma sequência de escape \0 é substituída pelo texto correspondente.

Comentários:

• Esses erros de serviço externo são relatados ao usuário como estão, sem adicionar informações sobre a etapa de pré-processamento.

Verificar valor não suportado

Verifique se nenhum valor do item pôde ser recuperado. Especifique como a falha deve ser processada com base na inspeção da mensagem de erro retornada.

Parâmetros:

• scope - selecione o escopo do processamento do erro:
  qualquer erro - qualquer erro;
  erro corresponde - somente o erro que corresponde à expressão regular especificada em pattern;
  erro não corresponde - somente o erro que não corresponde à expressão regular especificada em pattern
  
• pattern - a expressão regular usada para corresponder ao erro. Se qualquer erro estiver selecionado no parâmetro de escopo, este campo não será exibido. Quando exibido, este campo é obrigatório.
  

Comentários:

• Normalmente, a ausência de um valor ou a falha ao recuperá-lo faria com que o item se tornasse não suportado. Esta etapa de pré-processamento permite modificar esse comportamento.
• Esta etapa de pré-processamento verifica somente se nenhum valor do item pôde ser recuperado. Ela não verifica, por exemplo, se o tipo do valor recuperado (por exemplo, string) corresponde ao tipo de informação do item (por exemplo, numérico); para obter detalhes, consulte Exemplos de pré-processamento. Se houver uma incompatibilidade de tipos, o item ainda poderá se tornar não suportado após a execução de todas as etapas de pré-processamento. Para verificar uma incompatibilidade de tipos, você pode usar, por exemplo, a etapa de pré-processamento Multiplicador personalizado; consulte Exemplos de pré-processamento.
• Há suporte para grupos de expressões regulares de captura nos campos Definir valor como ou Definir erro como. Use \N (onde N=1…9) para recuperar o N-ésimo grupo correspondente; use \0 para recuperar o texto correspondente;
• Essas etapas são sempre executadas como as primeiras etapas de pré-processamento e são posicionadas acima de todas as outras após salvar as alterações no item;
• Há suporte para várias etapas de Verificar valor não suportado, na ordem especificada. Uma etapa para qualquer erro será posicionada automaticamente como a última etapa deste grupo.

Descartar inalterado

Descarta um valor se ele não foi alterado.

Comentários:

• Se um valor for descartado, ele não será salvo no banco de dados e o Zabbix server não terá conhecimento de que esse valor foi recebido. Nenhuma expressão de trigger será avaliada, como resultado, nenhum problema para triggers relacionadas será criado/resolvido. Funções funcionarão apenas com base nos dados que estão realmente salvos no banco de dados. Como as tendências são construídas com base nos dados do banco de dados, se não houver valor salvo para uma hora, também não haverá dados de tendências para essa hora.
  
• Apenas uma opção de limitação pode ser especificada por item.

Descartar valores inalterados com heartbeat

Descarta um valor se ele não tiver sido alterado dentro do período definido (em segundos).

Comentários:

• Valores inteiros positivos são aceitos para especificar os segundos (mínimo de 1 segundo);
  
• Sufixos de tempo podem ser usados (por exemplo, 30s, 1m, 2h, 1d);
  
• Macros de usuário e macros de descoberta de baixo nível podem ser usadas;
  
• Se um valor for descartado, ele não será salvo no banco de dados e o Zabbix server não terá conhecimento de que esse valor foi recebido. Nenhuma expressão de trigger será avaliada e, como resultado, nenhum problema para os triggers relacionados será criado ou resolvido. As funções funcionarão somente com base nos dados efetivamente salvos no banco de dados. Como os dados de tendências são criados com base nos dados do banco de dados, se nenhum valor for salvo durante uma hora, também não haverá dados de tendências para essa hora.
  
• Somente uma opção de limitação pode ser especificada por item.

Padrão Prometheus

Use a seguinte consulta para extrair os dados necessários das métricas do Prometheus.

Veja Prometheus checks para mais detalhes.

Prometheus para JSON

Converta as métricas Prometheus necessárias para JSON.

Veja Prometheus checks para mais detalhes.

Suporte a macros

Macros de usuário e macros de usuário com contexto são suportadas em:

• parâmetros de etapas de pré-processamento, incluindo código JavaScript;
• parâmetros de tratamento de erro personalizado (campos Definir valor como e Definir erro como).

Testando

Veja testando pré-processamento.