1 Macros de usuário

Visão geral

Para melhorar a flexibilidade de configuração o Zabbix suporta macros de usuário que podem ser definidas em três níveis:

  • Global
  • Template
  • Host

A partir do Zabbix 3.0.0 é possível ainda definir contextos para as macros, com o contexto é possível especificar macros com textos adicionais de identificação.

Estas macros tem uma sintaxe especial: {$MACRO}. É possível selecionar a macro de um contexto específico, usando esta configuração a relação hierárquica de contextos de macros será ignorada. As macros de usuário com contexto forçado devem usar a seguinte sintaxe:: {$MACRO:​contexto}.

Podem ser utilizadas em:

  • nomes de itens
  • parâmetros de chaves de item
  • nomes e descrições de triggers
  • constantes e parâmetros de expressões de trigger
  • vários outros locais

Os seguintes caracteres podem ser utilizados em nomes de macros: A-Z , 0-9 , _ , .

O Zabbix substitui o valor das macros com a seguinte ordem de precedência:

  1. nível de host (verificado primeiro)
  2. primeiro nível de template (templates diretamente associados ao host), ordenados pelo ID de template
  3. segundo nível de template (templates associados ao template que foi diretamente associado ao host), ordenados pelo ID de template
  4. segundo nível de template (templates associados aos templates associados ao template que foi diretamente associado ao host), ordenados pelo ID de template
  5. ...
  6. macros globais (verificadas por último)

Em outras palavras, se a macro não existir no host, o Zabbix tentará localiza-la nos templates associados ao host. Se continuar não encontrando, a buscará nas macros globais.

Se o Zabbix não encontrar o valor da macro, ele não irá substituí-la.

A definição das macros de usuário podem ocorrer em três locais:

  • para macros globais: Administração → Geral → Macros
  • para macros de template: Configuração → Templates abra o template desejado e olhe na aba Macros
  • para macros de hosts: Configuração → Hosts abra o host desejado e olhe na aba Macros

Se uma macro de usuário for utilizada em itens ou triggers de um template é uma boa prática que ela seja adicionada no nível de template com um valor padrão. Desta forma exportando o template como um XML e importando em outro local o mesmo funcionará como o esperado.

Casos comuns de uso de macros de usuário e globais:

  1. para definir itens que precisam de senhas, números de porta, nomes de arquivos, etc em nível de template e definir seus valores em nível de host
  2. para definir em nível global um valor padrão para determinada característica (como por exemplo o nome da comunidade SNMP)

Contexto de macros

O contexto de uma macro é definido por um texto. O uso mais comum de macros baseadas em contexto é quando precisamos utiliza-las em uma LLD. Por exemplo, quando um protótipo de trigger precisa ser definida para uma descoberta de sistema de arquivos usando um limite personalizado para o aviso de pouco espaço livre, dependendo do tipo do sistema de arquivos.

Apenas as macros de descoberta são suportadas nos contextos. Qualquer outra macro é ignorada e tratada como um texto simplesmente.

Tecnicamente, o contexto da macro é definido usando regras similares às de uma chave de item, exceto relativo ao uso do caracter ,​:

  • O contexto de uma macro deve ser escapado usando aspas duplas <​nowiki>"</​nowiki>​, se o contexto contiver o caractere ​}​ ou iniciar com <​nowiki>"</​nowiki>​. As aspas dentro do texto escapado deverão conter o caractere ​\​. O caracter ​\​ em si não suporta ser "escapado", por causa disso é impossível ter uma macro terminando com o caractere ​\​ - a macro a seguir, por exemplo, é inválida ​{$MACRO:<​nowiki>"</​nowiki>​a:​\b\c\<​nowiki>"</​nowiki>​}.
  • Os espaços à esquerda do contexto serão ignorados, os espaços a direita não. Por exemplo: ​{$MACRO:​A}​ é o mesmo que ​{$MACRO:​ A},​ mas é diferente de ​{$MACRO:​A }​.
  • Todos os espaços antes do parêntese esquerdo e após a aspa de fechamento são ignorados, mas todos os espaços dentro dos parênteses são considerados. As macros ​{$MACRO:<​nowiki>"</​nowiki>​A<​nowiki>"</​nowiki>​},​ ​{$MACRO:​ <​nowiki>"</​nowiki>​A<​nowiki>"</​nowiki>​},​ ​{$MACRO:<​nowiki>"</​nowiki>​A<​nowiki>"</​nowiki>​ }​ e ​{$MACRO:​ <​nowiki>"</​nowiki>​A<​nowiki>"</​nowiki>​ }​ são as mesmas, enquanto as macros ​{$MACRO:<​nowiki>"</​nowiki>​A<​nowiki>"</​nowiki>​}​ e ​{$MACRO:<​nowiki>"</​nowiki>​ A <​nowiki>"</​nowiki>​}​ não são.

As seguintes macros são equivalentes, pois estão no mesmo contexto: ​{$MACRO:​A},​ ​{$MACRO:​ A}​ e ​{$MACRO:<​nowiki>"</​nowiki>​A<​nowiki>"</​nowiki>​}​. Esta é uma diferença quando comparadas com as chaves de itens, pois ​key[a],​ ​key[ a]​ e ​key[<​nowiki>"</​nowiki>​a<​nowiki>"</​nowiki>​]​ são semanticamente iguais, mas diferente para os critérios de unicidade.

Quando os contextos de macros são processados, o Zabbix analisa a macro no seu contexto. Se uma macro com um contexto não foi definida no host ou nos templates associados, tampouco no nível global, a macro sem contexto será requisitada para definir o valor.

Exemplos

Exemplo 1

Usando macro em nível de host para a chave do item "Status of SSH daemon":

net.tcp.service[ssh,,{$SSH_PORT}]

Desta forma o item pode variar sua porta de um host para outro, bastando que se configure o valor da macro {$SSH_PORT} no mesmo.

Exemplo 2

Usando macro em nível de usuário para a trigger "CPU load is too high":

{ca_001:system.cpu.load[,avg1].last()}>{$MAX_CPULOAD}

Desta forma a trigger pode ser criada em um template sem precisar ser editada em cada host.

Se você precisar usar a quantidade de valores de uma função como parâmetro (por exemplo, max(#3)), inclua o caractere "#" no valor da macro, por exemplo: {$SOME_PERIOD} = #3

Exemplo 3

Usar duas macros na trigger "CPU load is too high":

{ca_001:system.cpu.load[,avg1].min({$CPULOAD_PERIOD})}>{$MAX_CPULOAD}

Observe que uma macro pode ser usada como um parâmetro de uma trigger, como neste caso a função min().

Em uma expressão de trigger as macros de usuário serão expandidas para referenciar um parâmetro ou constante. Elas não serão expandidas para se referenciar ao host, chave do item, função, operador ou outro elemento da expressão.

Exemplo 4

Definir o espaço livre em disco em um protótipo de trigger no host:

​{ca_001:​vfs.fs.size[{#​FSNAME},​pfree].last()}<​{$LOW_SPACE_LIMIT:​"{#​FSNAME}"}

Adicionar as macros:

  • ​{$LOW_SPACE_LIMIT}10
  • ​{$LOW_SPACE_LIMIT:/​tmp}50

No exemplo acima, digamos que existam os seguintes pontos de montagem em seu ambiente: /,​ /​home​ e /​tmp. Os eventos serão criados quando o espaço livre nos pontos de montagem / e​ /​home​ possuírem menos de 10% de espaço livre, enquanto o alerta para o /tmp irá ocasionar a criação de um evento quando o espaço livre estiver inferior a 50%.