Esta é uma tradução da página de documentação original em inglês. Ajude-nos a torná-la melhor.

2 Macros de usuário

Visão geral

Macros de usuário são suportadas no Zabbix para maior flexibilidade, além de para as macros suportadas sai da caixa.

As macros de usuário podem ser definidas em nível global, de modelo e de host. Esses macros têm uma sintaxe especial:

{$MACRO}

O Zabbix resolve macros de acordo com a seguinte precedência:

  1. macros de nível de host (verificadas primeiro)
  2. macros definidas para modelos de primeiro nível do host (ou seja, modelos vinculados diretamente ao host), classificados por ID de modelo
  3. macros definidas para modelos de segundo nível do host, classificadas por ID do modelo
  4. macros definidas para modelos de terceiro nível do host, classificadas por ID do modelo, etc.
  5. macros globais (marcadas por último)

Em outras palavras, se uma macro não existir para um host, o Zabbix tentará encontre-o nos modelos de host de profundidade crescente. Se ainda não for encontrado, um macro global será usada, se existir.

Se uma macro com o mesmo nome existir em vários modelos vinculados do mesmo nível, a macro do modelo com o ID mais baixo será usado. Assim tendo macros com o mesmo nome em vários modelos é um risco de configuração.

Se o Zabbix não conseguir encontrar uma macro, a macro não será resolvida.

::: não importante Macros (incluindo macros de usuário) são deixadas sem solução na seção Configuração (por exemplo, na lista de gatilhos) por design para tornar a configuração complexa mais transparente. :::

As macros do usuário podem ser usadas em:

  • parâmetro chave do item
  • intervalos de atualização de itens e intervalos flexíveis
  • nome e descrição do gatilho
  • acionar parâmetros e constantes de expressão (consulte exemplos)
  • muitos outros locais - veja o completo lista
Common use cases of global and host macros
  • use a global macro in several locations; then change the macro value and apply configuration changes to all locations with one click
  • take advantage of templates with host-specific attributes: passwords, port numbers, file names, regular expressions, etc.

Configuration

To define user macros, go to the corresponding location in the frontend:

  • for global macros, visit Administration → General → Macros
  • for host and template level macros, open host or template properties and look for the Macros tab

If a user macro is used in items or triggers in a template, it is suggested to add that macro to the template even if it is defined on a global level. That way, if the macro type is text exporting the template to XML and importing it in another system will still allow it to work as expected. Values of secret macros are not exported.

A user macro has the following attributes:

Parameter Description
Macro Macro name. The name must be wrapped in curly brackets and start with a dollar sign.
Example: {$FRONTEND_URL}. The following characters are allowed in the macro names: A-Z (uppercase only) , 0-9 , _ , .
Value Macro value. Three value types are supported:
Text (default) - plain-text value
Secret text - the value is masked with asterisks, which could be useful to protect sensitive information such as passwords or shared keys.
Vault secret - the value contains a reference path (as 'path:key', for example “secret/zabbix:password”) to a Vault secret

Note that while the value of a secret macro is hidden from sight, the value can be revealed through the use in items. For example, in an external script an 'echo' statement referencing a secret macro may be used to reveal the macro value to the frontend because Zabbix server has access to the real macro value.

To select the value type click on the button at the end of the value input field:
icon indicates a text macro;
icon indicates a secret text macro. Upon hovering, the value field transforms into a button, which allows to enter a new value of the macro (to exit without saving a new value, click the backwards arrow ().
icon indicates a secret Vault macro.

Maximum length of a user macro value is 2048 characters (255 characters in versions before 5.2.0).
Description Text field used to provide more information about this macro.

URLs that contain a secret macro will not work as the macro in them will be resolved as "******".

In trigger expressions user macros will resolve if referencing a parameter or constant. They will NOT resolve if referencing a host, item key, function, operator or another trigger expression. Secret macros cannot be used in trigger expressions.

Examples

Example 1

Use of host-level macro in the "Status of SSH daemon" item key:

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

This item can be assigned to multiple hosts, providing that the value of {$SSH_PORT} is defined on those hosts.

Example 2

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

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

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

If you want to use the amount of values as the function parameter (for example, max(/host/key,#3)), include hash mark in the macro definition like this: SOME_PERIOD => #3

Example 3

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

min(/ca_001/system.cpu.load[,avg1],{$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:

nodata(/ca_001/agent.ping,{$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 the Working time field in AdministrationGeneralGUI;
  • use it in the When active field in AdministrationUserMedia;
  • 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 AdministrationGeneralMacros, if needed.
Example 6

Use host prototype macro to configure items for discovered hosts:

  • on a host prototype define user macro {$SNMPVALUE} with {#SNMPVALUE} low-level discovery macro as a value:

  • assign Generic SNMPv2 template to the host prototype;
  • use {$SNMPVALUE} in the SNMP OID field of Generic SNMPv2 template items.

User macro context

See user macros with context.