logmatic: Using Logmatic.io
The logmatic() destination sends log messages to the Logmatic.io Logging-as-a-Service provider. You can send log messages over TCP, or encrypted with TLS.
Declaration:
logmatic(token());
Example: Using the logmatic() driver
To use the logmatic() destination, the only mandatory parameter is your user token. The following example sends every log from the system() source to your Logmatic.io account.
log {
source { system(); };
destination { logmatic(token("<API-KEY-AS-PROVIDED-BY-LOGMATIC.IO>")); };
};
The following example uses TLS encryption. Before using it, download the CA certificate of Logmatic.io and copy it to your hosts (for example, into the /etc/ssl/certs/ directory.
log {
destination {
logmatic(token("<API-KEY-AS-PROVIDED-BY-LOGMATIC.IO>") port(6514)
tls(peer-verify(required-trusted) ca-dir('/etc/ssl/certs'))
);
};
};
The following example parses the access logs of an Apache webserver from a file and sends them to Logmatic.io in JSON format.
log {
source { file("/var/log/apache2/access.log" flags(no-parse)); };
parser { apache-accesslog-parser(); };
destination {
logmatic(token("<API-KEY-AS-PROVIDED-BY-LOGMATIC.IO>")
tag(apache)
template("$(format-json .apache.* timestamp=${ISODATE})"));
};
}To use the logmatic() driver, the scl.conf file must be included in your syslog-ng OSE configuration:
@include "scl.conf"
The logmatic() driver is actually a reusable configuration snippet configured to send log messages using the tcp() driver using a template. For details on using or writing such configuration snippets, see Reusing configuration blocks. You can find the source of this configuration snippet on GitHub.
logmatic() destination options
The logmatic() destination has the following options. You can also set other options of the underlying tcp() driver (for example, port number or TLS-encryption).
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
NOTE: The syslog-ng OSE application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable syslog-ng OSE to execute external applications.
Using the hook-commands() when syslog-ng OSE starts or stops
To execute an external program when syslog-ng OSE starts or stops, use the following options:
| startup() | |
| Type: | string |
| Default: | N/A |
|
Description: Defines the external program that is executed as syslog-ng OSE starts. | |
| shutdown() | |
| Type: | string |
| Default: | N/A |
|
Description: Defines the external program that is executed as syslog-ng OSE stops. | |
Using the hook-commands() when syslog-ng OSE reloads
To execute an external program when the syslog-ng OSE configuration is initiated or torn down, for example, on startup/shutdown or during a syslog-ng OSE reload, use the following options:
| setup() | |
| Type: | string |
| Default: | N/A |
|
Description: Defines an external program that is executed when the syslog-ng OSE configuration is initiated, for example, on startup or during a syslog-ng OSE reload. | |
| teardown() | |
| Type: | string |
| Default: | N/A |
|
Description: Defines an external program that is executed when the syslog-ng OSE configuration is stopped or torn down, for example, on shutdown or during a syslog-ng OSE reload. | |
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as syslog-ng OSE is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the syslog-ng OSE created rule is there, packets can flow, otherwise the port is closed.
source {
network(transport(udp)
hook-commands(
startup("iptables -I LOGCHAIN 1 -p udp --dport 514 -j ACCEPT")
shutdown("iptables -D LOGCHAIN 1")
)
);
};token()
| Type: | string |
| Default: |
Description: Your API Key that you received from Logmatic.io.
mongodb: Storing messages in a MongoDB database
The mongodb() driver sends messages to a MongoDB database. MongoDB is a schema-free, document-oriented database. For the list of available optional parameters, see mongodb() destination options.
Declaration:
mongodb(parameters);
The mongodb() driver does not support creating indexes, as that can be a very complex operation in MongoDB. If needed, the administrator of the MongoDB database must ensure that indexes are created on the collections.
The mongodb() driver does not add the _id field to the message: the MongoDB server will do that automatically, if none is present. If you want to override this field from syslog-ng OSE, use the key() parameter of the value-pairs() option.
The syslog-ng OSE mongodb() driver is compatible with MongoDB server version 1.4 and newer.
NOTE: By default, syslog-ng OSE handles every message field as a string. For details on how to send selected fields as other types of data (for example, handle the PID as a number), see Specifying data types in value-pairs.
Example: Using the mongodb() driver
The following example creates a mongodb() destination using only default values.
destination d_mongodb {
mongodb();
};
The following example displays the default values.
destination d_mongodb {
mongodb(
uri("mongodb://localhost:27017/syslog")
collection("messages")
value-pairs(
scope("selected-macros" "nv-pairs" "sdata")
)
);
};
The following example shows the same setup using the deprecated libmongo-client syntax (as used in syslog-ng OSE version
destination d_mongodb {
mongodb(
servers("localhost:27017")
database("syslog")
collection("messages")
value-pairs(
scope("selected-macros" "nv-pairs" "sdata")
)
);
};How syslog-ng OSE connects the MongoDB server
When syslog-ng OSE connects the MongoDB server during startup, it completes the following steps.
-
The syslog-ng OSE application connects the first address listed in the servers() option.
-
-
If the server is accessible and it is a master MongoDB server, syslog-ng OSE authenticates on the server (if needed), then starts sending the log messages to the server.
-
If the server is not accessible, or it is not a master server in a MongoDB replicaset and it does not send the address of the master server, syslog-ng OSE connects the next address listed in the servers() option.
-
If the server is not a master server in a MongoDB replicaset, but it sends the address of the master server, syslog-ng OSE connects the received address.
-
-
When syslog-ng OSE connects the master MongoDB server, it retrieves the list of replicas (from the replSet option of the server), and appends this list to the servers() option.
Caution: -
This means that syslog-ng OSE can send log messages to addresses that are not listed in its configuration.
-
Make sure to include the address of your master server in your syslog-ng OSE configuration file, otherwise you risk losing log messages if all the addresses listed in the syslog-ng OSE configuration are offline.
-
Addresses retrieved from the MongoDB servers are not stored, and can be lost when syslog-ng OSE is restarted. The retrieved addresses are not lost if the server() option of the destination was not changed in the configuration file since the last restart.
-
The failover mechanism used in the mongodb() driver is different from the client-side failover used in other drivers.
-
-
The syslog-ng OSE application attempts to connect another server if the servers() list contains at least two addresses, and one of the following events happens:
-
The safe-mode() option is set to no, and the MongoDB server becomes unreachable.
-
The safe-mode() option is set to yes, and syslog-ng OSE cannot insert a log message into the database because of an error.
In this case, syslog-ng OSE starts to connect the addresses in from the servers() list (starting from the first address) to find the new master server, authenticates on the new server (if needed), then continues to send the log messages to the new master server.
During this failover step, one message can be lost if the safe-mode() option is disabled.
-
-
If the original master becomes accessible again, syslog-ng OSE will automatically connect to the original master.
