14.1.2. Options of grouping-by parsers

The grouping-by has the following options.

aggregate()

Synopsis: aggregate()

Description: Specifies the message that syslog-ng OSE generates when the context is closed. Note that the aggregate() option has access to every message of the context, and has the following options:

  • inherit-mode: This attribute controls which name-value pairs and tags are propagated to the newly generated message.

    • context: syslog-ng OSE collects every name-value pair from each message stored in the context, and includes them in the generated message. If a name-value pair appears in multiple messages of the context, the value in the latest message will be used. Note that tags are not merged, the generated message will inherit the tags assigned to the last message of the context.

    • last-message: Only the name-value pairs appearing in the last message are copied. If the context contains only a single message, then it is the message that triggered the action.

    • none: An empty message is created, without inheriting any tags or name-value pairs.

    For details on the message context, see Section 14.1, Correlating messages using the grouping-by() parser.

  • tags:

  • value: Adds a name-value pair to the generated message. You can include text, macros, template functions, and you can also reference every message of the context. For details on accessing other messages of the context, see Section 14.1.1, Referencing earlier messages of the context.

having()

Synopsis: having()

Description: Specifies a filter: syslog-ng OSE generates the aggregate message only if the result of the filter expression is true. Note that the having() filter has access to every message of the context. For details on accessing other messages of the context, see Section 14.1.1, Referencing earlier messages of the context.

inject-mode()

Synopsis: inject-mode()

Description: By default, the aggregated message that syslog-ng OSE generates is injected into the same place where the grouping-by() statement is referenced in the log path. To post the generated message into the internal() source instead, use the inject-mode() option in the definition of the parser.

Example 14.5. Sending triggered messages to the internal() source

To send the generated messages to the internal source, use the inject-mode("internal") option:

parser p_grouping-by {grouping-by(
    ...
    inject-mode("internal")
);};

To inject the generated messages where the parser is referenced, use the inject-mode("pass-through") option:

parser p_grouping-by {grouping-by(
    ...
    inject-mode("pass-through")
);};

You can configure the generated message in the aggregate() option (see Section aggregate()). You can create an entire message, use macros and values extracted from the original message, and so on.

key()

Synopsis: key()

Description: Specifies the key (that is, the name of a name-value pair) that every message must have to be added to the context. The value of the key must be the same for every message of the context. For example, this can be a session-id parsed from firewall messages, and so on.

scope()

Synopsis: scope()

Description: Specifies which messages belong to the same context. The following values are available:

  • process: Only messages that are generated by the same process of a client belong to the same context, that is, messages that have identical ${HOST}, ${PROGRAM} and ${PID} values. This is the default behavior of syslog-ng OSE if context-scope is not specified.

  • program: Messages that are generated by the same application of a client belong to the same context, that is, messages that have identical ${HOST} and ${PROGRAM} values.

  • host: Every message generated by a client belongs to the same context, only the ${HOST} value of the messages must be identical.

  • global: Every message belongs to the same context.

timeout()

Synopsis: timeout([seconds])

Description: Specifies the maximum time to wait for all messages of the context to arrive. If no new message is added to the context during this period, the context is assumed to be complete and syslog-ng OSE generates and sends the triggered message (specified in the aggregate() option), and clears the context. If a new message is added to the context, the timeout period is restarted.

trigger()

Synopsis: trigger()

Description: A filter that specifies the final message of the context. If the filter matches the incoming message, syslog-ng OSE generates and sends the triggered message (specified in the aggregate() option), and clears the context.

where()

Synopsis: where()

Description: Specifies a filter condition. Messages not matching the filter will not be added to the context. Note that the where() filter has access only to the current message.