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 realizadas pelo Zabbix server ou proxy (se os itens forem monitorados por proxy).

Esse recurso suporta uma variedade de casos de uso, como:

• converter bytes em bits (por exemplo, multiplicando 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 anteriores, 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 guia Pré-processamento do formulário de configuração do item.

Clique em Adicionar para selecionar uma transformação suportada.

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

Transformações suportadas

Todas as transformações suportadas estão listadas abaixo. Clique no nome da transformação para ver detalhes completos sobre ela.

Observe que para as etapas de pré-processamento Mudança e Limitação, o Zabbix precisa lembrar 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 proxy for reiniciado ou houver qualquer alteração feita nas etapas de pré-processamento, o último valor do item correspondente será redefinido, resultando em:

• para as etapas Mudança simples, Mudança por segundo - o próximo valor será ignorado porque não há valor anterior para calcular a mudança;
• para as etapas Descartar inalterado, Descartar inalterado com heartbeat - o próximo valor nunca será descartado, mesmo que devesse ter sido devido às regras de descarte.

Expressão regular

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

Parâmetros:

• pattern - a expressão regular;
  
• output - o modelo de formatação de 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 tornará o item não suportado;
  
• A expressão regular suporta a extração de no máximo 10 grupos capturados com a sequência \N;
  
• Se você marcar a caixa Personalizado em caso de falha, é possível especificar opções personalizadas de tratamento de erro: descartar o valor, definir um valor especificado ou definir uma mensagem de erro especificada. Em caso de falha na etapa de pré-processamento, o item não se tornará não suportado se a opção de descartar o valor ou definir um valor especificado for selecionada.
  
• Consulte a seção de expressões regulares para 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

Extrai valor ou fragmento de dados XML usando a funcionalidade XPath.

Comentários:

• Para que esta opção funcione, o Zabbix server (ou Zabbix proxy) deve ser compilado com suporte a libxml;
  
• Namespaces não são suportados;
  
• Se você marcar a caixa Personalizado em caso de falha, é possível especificar opções personalizadas de tratamento de erro: descartar o valor, definir um valor específico ou definir uma mensagem de erro específica. Em caso de falha na etapa de pré-processamento, o item não ficará como não suportado se a opção de descartar o valor ou definir um valor específico for selecionada.

Exemplos:

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

JSON Path

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

Se você marcar a caixa Personalizado em caso de falha, é possível especificar opções personalizadas de tratamento de erro: descartar o valor, definir um valor especificado ou definir uma mensagem de erro especificada. Em caso de falha na etapa de pré-processamento, o item não ficará como não suportado se a opção de descartar o valor ou definir um valor especificado for selecionada.

CSV para JSON

Converte dados de arquivo CSV para o formato JSON.

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

XML para JSON

Converte dados no formato XML para JSON.

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

Se você marcar a caixa Personalizado em caso de falha, é possível especificar opções personalizadas de tratamento de erro: descartar o valor, definir um valor especificado ou definir uma mensagem de erro especificada. Em caso de falha na etapa de pré-processamento, o item não ficará como não suportado se a opção de descartar o valor ou definir um valor especificado for selecionada.

Valor SNMP walk

Extrai o valor pelo OID/nome MIB especificado e aplica opções de formatação:

• Inalterado - retorna a string hexadecimal como string hexadecimal não escapada (note que dicas de exibição ainda são aplicadas);
  
• UTF-8 de hex-STRING - converte a string hexadecimal para string UTF-8;
  
• MAC de hex-STRING - valida a string hexadecimal como endereço MAC e retorna uma string de endereço MAC adequada (onde ' ' são substituídos por ':');
  
• Inteiro de BITS - converte os primeiros 8 bytes de uma string 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 strings de bits maiores que 8 bytes, os bytes subsequentes serão ignorados.

Se você marcar a caixa de seleção Personalizado em caso de falha, é possível especificar opções personalizadas de tratamento de erro: descartar o valor, definir um valor especificado ou definir uma mensagem de erro especificada. Em caso de falha na etapa de pré-processamento, o item não ficará como não suportado se a opção de descartar o valor ou definir um valor especificado for selecionada.

SNMP walk para JSON

Converte valores SNMP para JSON.

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

Comentários:

• Opções de formatação de valor semelhantes às da etapa Valor SNMP walk estão disponíveis;
  
• Você pode usar esta etapa de pré-processamento para descoberta de SNMP OID;
  
• Se você marcar a caixa Personalizar em caso de falha, é possível especificar opções personalizadas de tratamento de erro: descartar o valor, definir um valor especificado ou definir uma mensagem de erro especificada. Em caso de falha na etapa de pré-processamento, o item não ficará como não suportado se a opção de descartar o valor ou definir um valor especificado for selecionada.

Valor SNMP get

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

• UTF-8 de Hex-STRING - converte hex-string para string UTF-8;
  
• MAC de Hex-STRING - valida hex-string como endereço MAC e retorna uma string de endereço MAC adequada (onde ' ' são substituídos por ':');
  
• Inteiro de BITS - converte os primeiros 8 bytes de uma string 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 strings de bits maiores que 8 bytes, os bytes subsequentes serão ignorados.

Se você marcar a caixa Personalizado em caso de falha, é possível especificar opções personalizadas de tratamento de erro: descartar o valor, definir um valor especificado ou definir uma mensagem de erro especificada. Em caso de falha em uma etapa de pré-processamento, o item não ficará como não suportado se a opção de descartar o valor ou definir um valor especificado for selecionada.

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., em 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 com o tipo de informação definido como Numérico (sem sinal) e o valor calculado resultante for realmente um número de ponto flutuante, o valor calculado ainda será aceito como correto, truncando a parte decimal e armazenando o valor como um inteiro;
  
• Suportado: 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.
• Se você marcar a caixa de seleção Personalizado em caso de falha, é possível especificar opções personalizadas de tratamento de erro: descartar o valor, definir um valor especificado ou definir uma mensagem de erro especificada. Em caso de uma etapa de pré-processamento com falha, o item não se tornará não suportado se a opção de descartar o valor ou definir um valor especificado for selecionada.

Mudança simples

Calcula 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, onde value - o valor atual; prev_value - o valor recebido anteriormente;
  
• Apenas uma operação de mudança por item ("Mudança simples" ou "Mudança por segundo") é permitida;
• Se o valor atual for menor que o valor anterior, o Zabbix descarta essa diferença (não armazena nada) e aguarda outro valor;
  
• Se você marcar a caixa Personalizar em caso de falha, é possível especificar opções personalizadas de tratamento de erro: descartar o valor, definir um valor especificado ou definir uma mensagem de erro especificada. Em caso de falha na etapa de pré-processamento, o item não ficará como não suportado se a opção de descartar o valor ou definir um valor especificado for selecionada.

Alteração por segundo

Calcula 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 (float), mesmo que os valores brutos recebidos sejam inteiros. Isso é especialmente relevante para números pequenos, onde a parte decimal é importante. Se os valores de ponto flutuante forem grandes e puderem exceder o comprimento do campo 'float', caso em que todo o valor pode ser perdido, é recomendável usar Numérico (sem sinal) e, assim, cortar apenas a parte decimal.
  
• Avaliado como (valor-valor_anterior)/(tempo-tempo_anterior), onde valor - o valor atual; valor_anterior - o valor recebido anteriormente; tempo - o timestamp atual; tempo_anterior - 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 descarta essa diferença (não armazena nada) e aguarda outro valor. Isso ajuda a funcionar corretamente, por exemplo, com o estouro (overflow) de contadores SNMP de 32 bits.
  
• Se você marcar a caixa Personalizado em falha, é possível especificar opções personalizadas de tratamento de erro: descartar o valor, definir um valor especificado ou definir uma mensagem de erro especificada. Em caso de falha na etapa de pré-processamento, o item não ficará como não suportado se a opção de descartar o valor ou definir um valor especificado for selecionada.

Booleano para decimal

Converte o valor do formato booleano para decimal.

Comentários:

• A representação textual é traduzida para 0 ou 1. Assim, 'TRUE' é armazenado como 1 e 'FALSE' é armazenado como 0. Todos os valores são comparados de forma case-insensitive. Atualmente, os valores reconhecidos 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.
  
• Se você marcar a caixa Personalizar em caso de falha, é possível especificar opções personalizadas de tratamento de erro: descartar o valor, definir um valor especificado ou definir uma mensagem de erro especificada. Em caso de falha na etapa de pré-processamento, o item não ficará como não suportado se a opção de descartar o valor ou definir um valor especificado for selecionada.

Octal para decimal

Converte o valor do formato octal para decimal.

Se você marcar a caixa de seleção Personalizado em caso de falha, é possível especificar opções personalizadas de tratamento de erro: descartar o valor, definir um valor especificado ou definir uma mensagem de erro especificada. Em caso de falha na etapa de pré-processamento, o item não ficará como não suportado se a opção de descartar o valor ou definir um valor especificado for selecionada.

Hexadecimal para decimal

Converte o valor do formato hexadecimal para decimal.

Se você marcar a caixa de seleção Personalizado em caso de falha, é possível especificar opções personalizadas de tratamento de erro: descartar o valor, definir um valor especificado ou definir uma mensagem de erro especificada. Em caso de falha na etapa de pré-processamento, o item não ficará como não suportado se a opção de descartar o valor ou definir um valor especificado for selecionada.

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 em que um valor deve estar, especificando valores mínimos/máximos (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;
  
• Pelo menos um valor deve existir;
  
• Macros de usuário e macros de descoberta de baixo nível podem ser usadas;
  
• Se você marcar a caixa Personalizado em falha, é possível especificar opções personalizadas de tratamento de erro: descartar o valor, definir um valor especificado ou definir uma mensagem de erro especificada. Em caso de falha na etapa de pré-processamento, o item não ficará como não suportado se a opção de descartar o valor ou definir um valor especificado for selecionada.

Corresponde à expressão regular

Especifique uma expressão regular que um valor deve corresponder.

Se você marcar a caixa Personalizado em falha, é possível especificar opções personalizadas de tratamento de erro: descartar o valor, definir um valor especificado ou definir uma mensagem de erro especificada. Em caso de falha na etapa de pré-processamento, o item não ficará como não suportado se a opção de descartar o valor ou definir um valor especificado for selecionada.

Não corresponde à expressão regular

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

Se você marcar a caixa de seleção Personalizado em falha, é possível especificar opções personalizadas de tratamento de erro: descartar o valor, definir um valor especificado ou definir uma mensagem de erro especificada. Em caso de falha na etapa de pré-processamento, o item não ficará como não suportado se a opção de descartar o valor ou definir um valor especificado for selecionada.

Verificar erro no JSON

Verifica por uma mensagem de erro em nível de aplicação localizada no JSONPath. Interrompe o processamento se for bem-sucedido e a mensagem não estiver vazia; caso contrário, continua o processamento com o valor que estava antes desta etapa de pré-processamento.

Comentários:

• Esses erros de serviço externo são relatados ao usuário como estão, sem adicionar informações da etapa de pré-processamento;
  
• Nenhum erro será relatado em caso de falha ao analisar um JSON inválido;
  
• Se você marcar a caixa Personalizado em caso de falha, é possível especificar opções personalizadas de tratamento de erro: descartar o valor, definir um valor especificado ou definir uma mensagem de erro especificada. Em caso de falha na etapa de pré-processamento, o item não ficará como não suportado se a opção de descartar o valor ou definir um valor especificado for selecionada.

Verificar erro no XML

Verifica por uma mensagem de erro em nível de aplicação localizada no XPath. Interrompe o processamento se for bem-sucedido e a mensagem não estiver vazia; caso contrário, continua o processamento com o valor que estava antes desta etapa de pré-processamento.

Comentários:

• Esses erros de serviço externo são relatados ao usuário como estão, sem adicionar informações da etapa de pré-processamento;
  
• Nenhum erro será relatado em caso de falha ao analisar um XML inválido;
  
• Se você marcar a caixa Personalizado em caso de falha, é possível especificar opções personalizadas de tratamento de erro: descartar o valor, definir um valor especificado ou definir uma mensagem de erro especificada. Em caso de falha na etapa de pré-processamento, o item não ficará como não suportado se a opção de descartar o valor ou definir um valor especificado for selecionada.

Verificar erro usando uma expressão regular

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

Parâmetros:

• pattern - a expressão regular;
  
• output - o modelo de formatação de 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:

• Esses erros de serviço externo são relatados ao usuário como estão, sem adicionar informações da etapa de pré-processamento;
  
• Se você marcar a caixa Personalizado em caso de falha, é possível especificar opções personalizadas de tratamento de erro: descartar o valor, definir um valor especificado ou definir uma mensagem de erro especificada. Em caso de falha na etapa de pré-processamento, o item não ficará como não suportado se a opção de descartar o valor ou definir um valor especificado for selecionada.

Verificar valor não suportado

Verifica se nenhum valor de 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 de processamento do erro:
  qualquer erro - qualquer erro;
  erro corresponde - apenas o erro que corresponde à expressão regular especificada em pattern;
  erro não corresponde - apenas o erro que não corresponde à expressão regular especificada em pattern
  
• pattern - a expressão regular para comparar com o erro. Se qualquer erro for selecionado no parâmetro scope, este campo não será exibido. Se exibido, este campo é obrigatório.
  

Comentários:

• Normalmente, a ausência/falha ao recuperar um valor faria com que o item se tornasse não suportado. Esta etapa de pré-processamento permite modificar esse comportamento. Se você marcar a caixa Personalizar em caso de falha (sempre marcada e desabilitada para esta etapa de pré-processamento), é possível especificar opções personalizadas de tratamento de erro: descartar o valor, definir um valor especificado ou definir uma mensagem de erro especificada. Em caso de falha na etapa de pré-processamento, o item não se tornará não suportado se a opção de descartar o valor ou definir um valor especificado for selecionada.
• Esta etapa de pré-processamento apenas verifica se nenhum valor de 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 detalhes, consulte Exemplos de pré-processamento. Se houver incompatibilidade de tipo, o item ainda poderá se tornar não suportado após todas as etapas de pré-processamento serem executadas. Para verificar incompatibilidade de tipo, você pode usar, por exemplo, a etapa de pré-processamento Multiplicador personalizado; consulte Exemplos de pré-processamento.
• A captura de grupos de expressão regular é suportada 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 colocadas acima de todas as outras após salvar as alterações no item;
• Várias etapas Verificar valor não suportado são suportadas, na ordem especificada. Uma etapa para qualquer erro será automaticamente colocada como a última etapa neste 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 inalterado com heartbeat

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

Comentários:

• Valores inteiros positivos são suportados para especificar os segundos (mínimo - 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, como resultado, nenhum problema para triggers relacionadas será criado/resolvido. As 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.

Padrão Prometheus

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

Veja Verificações Prometheus para mais detalhes.

Prometheus para JSON

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

Consulte Verificações Prometheus 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.