syslog-ng Open Source Edition 3.16 - Release Notes

riemann() destination options

The riemann() driver sends metrics or events to a Riemann monitoring system.

The riemann() destination has the following options:

attributes()

Description: The attributes() option adds extra metadata to the Riemann event, that can be displayed on the Riemann dashboard. To specify the metadata to add, use the syntax of the value-pairs() option. For details on using value-pairs(), see Structuring macros, metadata, and other value-pairs.

description()

Description: The value to add as the description field of the Riemann event.

disk-buffer()

Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:

Options reliable() and disk-buf-size() are required options.

destination d_demo {
    network(
        "127.0.0.1"
        port(3333)
        disk-buffer(
            mem-buf-size(10000)
            disk-buf-size(2000000)
            reliable(yes)
            dir("/tmp/disk-buffer")
        )
    );
};

destination d_demo {
    network(
        "127.0.0.1"
        port(3333)
           disk-buffer(
            mem-buf-length(10000)
            disk-buf-size(2000000)
            reliable(no)
            dir("/tmp/disk-buffer")
        )
    );
};

event-time()

Description: Instead of the arrival time into Riemann, syslog-ng OSE can also send its own timestamp value.

This can be useful if Riemann is inaccessible for a while, and the messages are collected in the disk buffer until Riemann is accessible again. In this case, it would be difficult to differentiate between messages based on the arrival time only, because this would mean that there would be hundreds of messages with the same arrival time. This issue can be solved by using this option.

The event-time() option takes an optional parameter specifying whether the time format is in seconds or microseconds. For example:

event-time("$(* $UNIXTIME 1000000)" microseconds)
event-time("12345678" microseconds)
event-time("12345678" seconds)
event-time("12345678")

In case the parameter is omitted, syslog-ng OSE defaults to the seconds version. In case the event-time() option is omitted altogether, syslog-ng OSE defaults to the seconds version with $UNIXTIME.

Note that the time format parameter requires:

• riemann-c-client 1.10.0 or newer

  In older versions of riemann-c-client, the microseconds option is not available.

  In case your distribution does not contain a recent enough version of riemann-c-client and you wish to use microseconds, install a new version from .

  If you installed the new version in a custom location (instead of the default one), make sure that you append the directory of the pkg-config file (.pc file) to the environment variable export PKG_CONFIG_PATH=....

  After calling configure, you should see the following message in the case of successful installation:

  [...]
   Riemann destination (module): yes, microseconds: yes
  [...]

• Riemann 2.13 or newer

  Older versions of Riemann cannot handle microseconds. No error will be indicated, however, the time of the event will be set to the timestamp when the message arrived to Riemann.

destination d_riemann {
   riemann(
   server("127.0.0.1")
   port(5555)
   event-time("${UNIXTIME}")
   [...]
   );
};

flush-lines()

Description: The syslog-ng OSE application can send the messages in a batch to the Riemann server. To send messages in batches, increase the flush-lines() parameter (by default, it is set to 1). The syslog-ng OSE application waits for this number of lines to accumulate, and sends them off in a single batch. Increasing this number increases throughput as more messages are sent in a single batch, but also increases message latency. Note that currently the riemann() destination does not have a timeout for sending messages if the batch is not full.

For example, if you set flush-lines() to 100, syslog-ng OSE waits for 100 messages. If the source sends a few messages, but less than 100 messages, syslog-ng OSE will not send the messages to the destination. If you stop or reload syslog-ng OSE or in case of network sources, the connection with the client is closed, syslog-ng OSE automatically sends the unsent messages to the destination.

If an error occurs while sending the messages to the server, syslog-ng OSE will try to resend every message from the batch. If it does not succeed (you can set the number of retry attempts in the retries() option), syslog-ng OSE drops every message in the batch.

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.

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:

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:

source {
   network(transport(udp)
	hook-commands(
          startup("iptables -I LOGCHAIN 1 -p udp --dport 514 -j ACCEPT")
          shutdown("iptables -D LOGCHAIN 1")
        )
     );
};

host()

Description: The value to add as the host field of the Riemann event.

log-fifo-size()

Description: The number of messages that the output queue can store.

metric()

Description: The numeric value to add as the metric field of the Riemann event. If possible, include type-hinting as well, otherwise the Riemann server will interpret the value as a floating-point number. The following example specifies the SEQNUM macro as an integer.

metric(int("$SEQNUM"))

port()

Description: The port number of the Riemann server.

retries()

Description: The number of times syslog-ng OSE attempts to send a message to this destination. If syslog-ng OSE could not send a message, it will try again until the number of attempts reaches retries, then drops the message.

server()

Description: The hostname or IP address of the Riemann server.

service()

Description: The value to add as the service field of the Riemann event.

state()

Description: The value to add as the state field of the Riemann event.

tags()

Description: The list of tags to add as the tags field of the Riemann event. If not specified syslog-ng OSE automatically adds the tags already assigned to the message. If you set the tags() option, only the tags you specify will be added to the event.

throttle()

Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.

timeout()

Description: The value (in seconds) to wait for an operation to complete, and attempt to reconnect the Riemann server if exceeded. By default, the timeout is disabled.

ttl()

Description: The value (in seconds) to add as the ttl (time-to-live) field of the Riemann event.

type()

Description: The type of the network connection to the Riemann server: TCP, TLS, or UDP. For TLS connections, set the ca-file() option to authenticate the Riemann server, and the cert-file() and key-file() options if the Riemann server requires authentication from its clients.

Declaration 1:

destination d_riemann {
	riemann(
		server("127.0.0.1")
		port(5672)
		type(
		   "tls"
		   ca-file("ca")
		   cert-file("cert") 
		   key-file("key")
		)
	);
};

An alternative way to specify TLS options is to group them into a tls() block. This allows you to separate them and ensure better readability.

Declaration 2:

destination d_riemann {
	riemann(
		server("127.0.0.1")
		port(5672)
		type("tls")
		tls(
			ca-file("ca")
			cert-file("cert") 
			key-file("key")
		)
	);
};

Make sure that you specify TLS options either using type() or using the tls() block. Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.

type(
	"tls"
	ca-file("/opt/syslog-ng/etc/syslog-ng/riemann-cacert.pem")
	)

riemann(
	.
	.
	type("tls")
	tls(
          	ca-file("/opt/syslog-ng/etc/syslog-ng/riemann-cacert.pem")
	)

type(
	"tls"
	cert-file("/opt/syslog-ng/etc/syslog-ng/riemann-client-cert.pem")
	key-file("/opt/syslog-ng/etc/syslog-ng/riemann-client-cert.key")
	)

riemann(
	.
	.
	type("tls")
        tls(
              cert-file("/opt/syslog-ng/etc/syslog-ng/riemann-client-cert.pem")
              key-file("/opt/syslog-ng/etc/syslog-ng/riemann-client-cert.key")
       )

type(
	"tls"
	cert-file("/opt/syslog-ng/etc/syslog-ng/riemann-client-cert.pem")
	key-file("/opt/syslog-ng/etc/syslog-ng/riemann-client-cert.key")
	)

riemann(
	.
	.
	type("tls")
        tls(
              cert-file("/opt/syslog-ng/etc/syslog-ng/riemann-client-cert.pem")
              key-file("/opt/syslog-ng/etc/syslog-ng/riemann-client-cert.key")
       )