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

Estas macros tem uma sintaxe especial: {$MACRO}.

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

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)

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.

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().

Example 2

Use of host-level macro in the "CPU load is too high" trigger:

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

Such a trigger would be created on the template, not edited in individual hosts.

Example 3

Use of two macros in the "CPU load is too high" trigger:

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

Note that a macro can be used as a parameter of trigger function, in this example function min().

Example 4

Synchronize the agent unavailability condition with the item update interval:

• define {$INTERVAL} macro and use it in the item update interval;
• use {$INTERVAL} as parameter of the agent unavailability trigger:

{ca_001:agent.ping.nodata({$INTERVAL})}=1

Example 5

Centralize configuration of working hours:

• create a global {$WORKING_HOURS} macro equal to 1-5,09:00-18:00;
• use it in Administration → General → Working time;
• use it in User → Media → When active;
• use it to set up more frequent item polling during working hours:

• use it in the Time period action condition;
• adjust the working time in Administration → General → Macros, if needed.

User macro context

An optional context can be used in user macros, allowing to override the default value with context-specific one.

User macros with context have a similar syntax:

{$MACRO:context} 

Macro context is a simple text value. The common use case for macro contexts would be using a low-level discovery macro value as a user macro context. For example, a trigger prototype could be defined for mounted file system discovery to use a different low space limit depending on the mount points or file system types.

Only low-level discovery macros are supported in macro contexts. Any other macros are ignored and treated as plain text.

Technically, macro context is specified using rules similar to item key parameters, except macro context is not parsed as several parameters if there is a , character:

• Macro context must be quoted with " if the context contains a } character or starts with a " character. Quotes inside quoted context must be escaped with the \ character. The \ character itself is not escaped, which means it's impossible to have a quoted context ending with the \ character - the macro {$MACRO:"a:\b\c\"} is invalid.
• The leading spaces in context are ignored, the trailing spaces are not. For example {$MACRO:A} is the same as {$MACRO: A}, but not {$MACRO:A }.
• All spaces before leading quotes and after trailing quotes are ignored, but all spaces inside quotes are not. Macros {$MACRO:"A"}, {$MACRO: "A"}, {$MACRO:"A" } and {$MACRO: "A" } are the same, but macros {$MACRO:"A"} and {$MACRO:" A "} are not.

The following macros are all equivalent, because they have the same context: {$MACRO:A}, {$MACRO: A} and {$MACRO:"A"}. This is in contrast with item keys, where key[a], key[ a] and key["a"] are the same semantically, but different for uniqueness purposes.

When context macros are processed, Zabbix looks up the macro with its context. If a macro with this context is not defined by host or linked templates, and it is not a defined as a global macro with context, then the macro without context is searched for.

See usage example of macro context in a disk space trigger prototype and take limitation clause into consideration.