The grouping-by has the following options.
aggregate()
Description: Specifies the message that syslog-ng PE generates when the context is closed. This option is mandatory.
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 PE 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.
The default value of inherit-mode() is context.
For details on the message context, see Correlating messages using the grouping-by() parser.
-
tags: Adds the specified tag to the list of 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 Referencing earlier messages of the context.
having()
Description: Specifies a filter: syslog-ng PE 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 Referencing earlier messages of the context.
inject-mode()
Description: By default, the aggregated message that syslog-ng PE 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: 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 aggregate()). You can create an entire message, use macros and values extracted from the original message, and so on.
key()
Description: Specifies the key (that is, the name of a name-value pair) that every message must have in order 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.
This is a mandatory option.
NOTE: Messages that do not have a key will all belong to the same context.
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.
-
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. This is the default value.
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 PE 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.
This option is mandatory, and its value must be equal to or greater than 1.
trigger()
Description: A filter that specifies the final message of the context. If the filter matches the incoming message, syslog-ng PE generates and sends the triggered message (specified in the aggregate() option), and clears the context.
where()
Description: Specifies a filter condition. Messages not matching the filter will not be added to the context. The where() filter has access only to the current message.
Enriching log messages with external data
To properly interpret the events that the log messages describe, you must be able to handle log messages as part of a system of events, instead of individual information chunks. The syslog-ng PE application allows you to import data from external sources to include in the log messages, thus extending, enriching, and complementing the data found in the log message.
The syslog-ng PE application currently provides the following possibilities to enrich log messages.
In syslog-ng PE version 7.0 and later, you can use an external database file to add additional metadata to your log messages. For example, you can create a database (or export it from an existing tool) that contains a list of hostnames or IP addresses, and the department of your organization that the host belongs to, the role of the host (mailserver, webserver, and so on), or similar contextual information.
The database file is a simple text file in comma-separated value (CSV) format, where each line contains the following information:
-
A selector or ID that appears in the log messages, or the name of a filter that matches the messages, for example, the hostname.
-
The name of the name-value pair that syslog-ng PE adds to matching log messages.
-
The value of the name-value pairs.
For example, the following csv-file contains three lines identified with the IP address, and adds the host-role field to the log message.
192.168.1.1,host-role,webserver
192.168.2.1,host-role,firewall
192.168.3.1,host-role,mailserver
The database file
The database file must comply with the RFC4180 CSV format, with the following exceptions and limitations:
To add multiple name-value pairs to a message, include a separate line in the database for each name-value pair, for example:
192.168.1.1,host-role,webserver
192.168.1.1,contact-person,"John Doe"
192.168.1.1,contact-email,johndoe@example.com
Technically, add-contextual-data() is a parser in syslog-ng PE so you have to define it as a parser object.
Declaration
parser p_add_context_data {
add-contextual-data(
selector("$HOST"),
database("context-info-db.csv"),
);
};
You can also add data to messages that do not have a matching selector entry in the database using the default-selector() option.
If you modify the database file, you have to reload syslog-ng PE for the changes to take effect. If reloading syslog-ng PE or the database file fails for some reason, syslog-ng PE will keep using the last working database file.
Example: Adding metadata from a CSV file
The following example defines uses a CSV database to add the role of the host based on its IP address, and prefixes the added name-value pairs with .metadata. The destination includes a template that simply appends the added name-value pairs to the end of the log message.
@include "scl.conf"
source s_network {
network(port(5555));
};
destination d_local {
file("/tmp/test-msgs.log"
template("$MSG Additional metadata:[${.metadata.host-role}]")};
parser p_add_context_data {
add-contextual-data(
selector("$SOURCEIP"),
database("context-info-db.csv"),
default-selector("unknown"),
prefix(".metadata.")
);
};
log {
source(s_network);
parser(p_add_context_data);
destination(d_local);
};192.168.1.1,host-role,webserver
192.168.2.1,host-role,firewall
192.168.3.1,host-role,mailserver
unknown,host-role,unknown
To better control to which log messages you add contextual data, you can use filters as selectors. In this case, the first column of the CSV database file must contain the name of a filter. For each message, syslog-ng PE evaluates the filters in the order they appear in the database file. If a filter matches the message, syslog-ng PE adds the name-value pair related to the filter.
For example, the database file can contain the entries. (For details on the accepted CSV-format, see database().)
f_auth,domain,all
f_localhost,source,localhost
f_kern,domain,kernel
Note that syslog-ng PE does not evaluate other filters after the first match. For example, if you use the previous database file, and a message matches both the f_auth and f_localhost filters, syslog-ng PE adds only the name-value pair of f_auth to the message.
To add multiple name-value pairs to a message, include a separate line in the database for each name-value pair, for example:
f_localhost,host-role,firewall
f_localhost,contact-person,"John Doe"
f_localhost,contact-email,johndoe@example.com
You can also add data to messages that do not have a matching selector entry in the database using the default-selector() option.
You must store the filters you reference in a database in a separate file. This file is similar to a syslog-ng PE configuration file, but must contain only a version string and filters (and optionally comments). You can use the syslog-ng --syntax-only <filename> command to ensure that the file is valid. For example, the content of such a file can be:
@version: 7.0
filter f_localhost { host("mymachine.example.com") };
filter f_auth { facility(4) };
filter f_kern { facility(0) };
Declaration
parser p_add_context_data_filter {
add-contextual-data(
selector(filters("filters.conf")),
database("context-info-db.csv"),
prefix(".metadata.")
);
};
If you modify the database file, or the file that contains the filters, you have to reload syslog-ng PE for the changes to take effect. If reloading syslog-ng PE or the files fails for some reason, syslog-ng PE will keep using the last working version of the file.
