Templates and macros

The AxoSyslog application allows you to define message templates, and reference them from every object that can use a template. Templates can include strings, macros (for example, date, the hostname, and so on), and template functions. For example, you can use templates to create standard message formats or filenames. For a list of macros available in AxoSyslog, see Macros of AxoSyslog. Fields from the structured data (SD) part of messages using the new IETF-syslog standard can also be used as macros.

Declaration:

   template <template-name> {
        template("<template-expression>") <template-escape(yes)>;
    };

Template objects have a single option called template-escape(), which is disabled by default (template-escape(no)). This behavior is useful when the messages are passed to an application that cannot handle escaped characters properly. Enabling template escaping (template-escape(yes)) causes AxoSyslog to escape the ', ", and backslash characters from the messages.

Note: Starting with AxoSyslog version 4.5, template-escape(yes) escapes the top-level template function in case of nested template functions.

If you do not want to enable the template-escape() option (which is rarely needed), you can define the template without the enclosing braces.

   template <template-name> "<template-expression>";

You can also refer to an existing template from within a template. The result of the referred template will be pasted into the second template.

   template first-template "sample-text";
    template second-template "The result of the first-template is: $(template first-template)";

If you want to use a template only once, you can define the template inline, for example:

   destination d_file {
        file ("/var/log/messages" template("${ISODATE} ${HOST} ${MESSAGE}\n") );
    };

Macros can be included by prefixing the macro name with a $ sign, just like in Bourne compatible shells. Although using braces around macro names is not mandatory, and the "$MESSAGE" and "${MESSAGE}" formats are equivalent, using the "${MESSAGE}" format is recommended for clarity.

Macro names are case-sensitive, that is, "$message" and "$MESSAGE" are not the same.

To use a literal $ character in a template, you have to escape it. In AxoSyslog versions 3.4 and earlier, use a backslash \$. In version 3.5 and later, use $$.

Default values for macros can also be specified by appending the :- characters and the default value of the macro. If a message does not contain the field referred to by the macro, or it is empty, the default value will be used when expanding the macro. For example, if a message does not contain a hostname, the following macro can specify a default hostname.

${HOST:-default_hostname}

By default, AxoSyslog sends messages using the following template: ${ISODATE} ${HOST} ${MSGHDR}${MESSAGE}\\n. (The ${MSGHDR}${MESSAGE} part is written together because the ${MSGHDR} macro includes a trailing whitespace.)

Example: Using templates and macros

The following template (t_demo_filetemplate) adds the date of the message and the name of the host sending the message to the beginning of the message text. The template is then used in a file destination: messages sent to this destination (d_file) will use the message format defined in the template.

   template t_demo_filetemplate {
        template("${ISODATE} ${HOST} ${MESSAGE}\n");
    };
    destination d_file {
        file("/var/log/messages" template(t_demo_filetemplate));
    };

If you do not want to enable the template-escape() option (which is rarely needed), you can define the template without the enclosing braces. The following two templates are equivalent.

   template t_demo_template-with-braces {
        template("${ISODATE} ${HOST} ${MESSAGE}\n");
    };
    template t_demo_template-without-braces "${ISODATE} ${HOST} ${MESSAGE}\n";

Templates can also be used inline, if they are used only at a single location. The following destination is equivalent with the previous example:

   destination d_file {
        file ("/var/log/messages" template("${ISODATE} ${HOST} ${MESSAGE}\n") );
    };

The following file destination uses macros to daily create separate logfiles for every client host.

   destination d_file {
            file("/var/log/${YEAR}.${MONTH}.${DAY}/${HOST}.log");
    };