Good Practices : Custom macros, the best way to get rid of $ARG…$-type arguments.

This post is also available in: French

When you need to write or modify a command in Centreon, you sometimes come across unclear arguments such as $ARG1$ , $ARG2$… No need to say that we all hate them since there is no way we can remember them clearly.
We’d like to share with you a pretty simple method to help you write commands and remember/understand the arguments by using custom macros.

Quick reminder on “standard” command writing

Basically, when a user defines a command in Centreon, he has to define all arguments that are linked to this command. These arguments are called “standard macro” and are shortened « $ARG1$ » for the first argument, « $ARG2$ » for the second one, etc.

The user can define these macros in a service template or for a specific service. For example, you can create a command that monitor available disk space on Linux partition:

01_saisie_commande_traditionnelle

What we’d like to show in the screenshot is the “line command” part that writes: $ARG1$, $ARG2$, $ARG3$, $ARG4$, $ARG5$.
Here, a user defines the arguments related to the command in any order. The main issue is that these arguments are not really understandable: what does $ARG1$ mean? And $ARG2$??? In this particular case, no user can understand the meaning of these arguments if he doesn’t know the monitoring check « check_centreon_snmp_remote_storage ».

Examples in a command argument

With every version of Centreon, we’ve been trying to solve this problem. A first option is that the user can define an argument example.
For instance, in the previous screenshot, the example is: !/!80!90!$USER2$!1

This example can be used in a service template or for specific services. The user chooses a command and defines command arguments by this syntax. The main issue is that this syntax is pretty difficult to use. The user has to write a first exclamation point, then the first argument and then, another exclamation point and a second argument, etc. To make this clear, we can explain the syntax this way: «one argument ==one exclamation point. Two arguments == two exclamation points. N arguments == N exclamation points. ».
Even if it looks easy to understand the way it works, it is not that easy to understand when you have to read one, or explain a command to someone else and worse, to check if the syntax is correct! When an error is found in the configuration generation, the user has to check carefully each argument, exclamation point by exclamation point…

The description in a command argument

Another option is the possibility to give your argument a description when you create a command. In the first screenshot, arguments are detailed in « Argument descriptions » :

  • ARG1 : warning
  • ARG2 : critical
  • ARG3 : path, partition
  • ARG4 : community
  • ARG5 : SNMP version

When the user chooses a command, the description of argument is used to define a service or to define a service template.

02_saisie_service_avec_arguments_preremplis

The good point is that Centreon automatically creates the command line based on the arguments created by a user. The weak point is that he doesn’t write the description of arguments. Moreover, if he enters only one argument, the command doesn’t work. Indeed, the user would have to enter and maintain a common macro to all host services… which is more than complex. For example, the port of a DBMS can be written only once and its value can be the same for all monitoring services in this database…
The third solution allows the user to go further and to be more precise: it is the custom macros.

Custom macros

Custom macros are defined in the Centreon command and then, their value is put in a host or service templates, or a specific host or service.
Below the example of a command written with custom macros :

03_saisie_commande_macro_personnalisees

The most important part in this screenshot is highlighted in red:

image art cedric

The user defines his own macros, which is made possible by:

  1. prefixing the macro by $_ (dollar sign immediately followed by underscore sign)
  2. prefixing the macro by
      -HOST to define a macro on host or host template
      -SERVICE to define a macro on service or service template
  3. Defining explicitly the macro’s name : WARNING for example
  4. Finishing the macro with $ (dollar sign).

In the example above, we defined 2 custom macros of hosts (SNMPCOMMUNITY and SNMPVERSION) and 3 custom macros of services (DISK, WARNING and CRITICAL). The macros of hosts SNMPCOMMUNITY and SNMPVERSION are automatically filled by Centreon when the user defines a community SNMP and a version SNMP for a host.

04_saisie_communautesnmp_hote

The macros of services have to be defined on service or a service template:

05_saisie_macro_service

To sum it up, this is why you should use custom macros:

  1. They are clearly defined with a meaningful name chosen by the user (WARNING, MYSQLPASSWORD, NRPETCPPORT…);
  2. The legacy between service template and service is more flexible : for example, a service template can define one custom macro and let service defining the others;
  3. The overwriting of one macro is possible;
  4. A custom macro which is defined on a host can be shared by several services. You can use it to define, for example, some identical arguments on host, independently of the service. The main use case is the user name and password to connect to an application when this application is monitored by several services. An example: there are 10 services which monitor MySQL. The user name MySQL, the password and the port MySQL are all in custom macros of hosts. But, the database name is in a custom macro of service.

We hope all this explanation help you understand and manage custom macros!

Leave a Reply