7.18.1. riemann() destination options

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

The riemann() destination has the following options:

attributes()

Type: parameter list of the value-pairs() option
Default:  

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 Section 2.10, Structuring macros, metadata, and other value-pairs.

description()

Type: template, macro, or string
Default:  

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:

reliable()  
Type: yes|no
Default: no
 

Description: If set to yes, syslog-ng OSE cannot lose logs in case of reload/restart, unreachable destination or syslog-ng OSE crash. This solution provides a slower, but reliable disk-buffer option. It is created and initialized at startup and gradually grows as new messages arrive. If set to no, the normal disk-buffer will be used. This provides a faster, but less reliable disk-buffer option.

Warning

Hazard of data loss! If you change the value of reliable() option when there are messages in the disk-buffer, the messages stored in the disk-buffer will be lost.

dir()  
Type: string
Default: N/A
 Description: Defines the folder where the disk-buffer files are stored. This option has priority over --qdisk-dir=.
disk-buf-size()  
Type: number (bytes)
Default:  
 Description: This is a required option. The maximum size of the disk-buffer in bytes. The minimum value is 1048576 bytes. If you set a smaller value, the minimum value will be used automatically. It replaces the old log-disk-fifo-size() option.
mem-buf-length()  
Type: number (messages)
Default: 10000
 Description: Use this option if the option reliable() is set to no. This option contains the number of messages stored in overflow queue. It replaces the old log-fifo-size() option. It inherits the value of the global log-fifo-size() option if provided. If it is not provided, the default value is 10000 messages. Note that this option will be ignored if the option reliable() is set to yes.
mem-buf-size()  
Type: number (bytes)
Default: 163840000
 Description: Use this option if the option reliable() is set to yes. This option contains the size of the messages in bytes that is used in the memory part of the disk buffer. It replaces the old log-fifo-size() option. It does not inherit the value of the global log-fifo-size() option, even if it is provided. Note that this option will be ignored if the option reliable() is set to no.
qout-size()  
Type: number (messages)
Default: 64
 Description: The number of messages stored in the output buffer of the destination.

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

Example 7.36. Examples for using disk-buffer()

In the following case reliable disk-buffer() is used.

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")
            )
        );
};

In the following case normal disk-buffer() is used.

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()

Type: template, macro, or string
Default: ${UNIXTIME}

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.

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

flush-lines()

Type: number
Default: 1

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.

host()

Type: template, macro, or string
Default: ${HOST}

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

log-fifo-size()

Type: number
Default: Use global setting.

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

metric()

Type: template, macro, or string
Default:  

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()

Type: number
Default: 5555

Description: The port number of the Riemann server.

retries()

Type: number (of attempts)
Default: 3

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()

Type: hostname or IP address
Default: 127.0.0.1

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

service()

Type: template, macro, or string
Default: ${PROGRAM}

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

state()

Type: template, macro, or string
Default:  

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

tags()

Type: string list
Default: the tags already assigned to the message

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()

Type: number
Default: 0

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()

Type: number [seconds]
Default:  

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()

Type: template, macro, or number
Default:  

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

type()

Type: tcp | tls | udp
Default: tcp

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

cacert()  
Type: path to a CA certificate in PEM format
Default:  

Description: Path to the CA certificate in PEM format that signed the certificate of the Riemann server. When establishing TLS connection, syslog-ng OSE verifies the certificate of the Riemann server using this CA.

type(
	tls
	cacert("/opt/syslog-ng/etc/syslog-ng/riemann-cacert.pem")
	)
cert-file()  
Type: path to a certificate in PEM format
Default:  

Description: Path to the a certificate file in PEM format. When establishing TLS connection, syslog-ng OSE authenticates on the Riemann server using this certificate and the matching private key set in the key-file() option.

Note that you have to set the cert-file() and key-file() options only if the Riemann server requires authentication from the clients.

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")
	)

This option was called cert() in syslog-ng OSE version 3.7.

key-file()  
Type: path to a private key file
Default:  

Description: Path to the private key of the certificate file set in the cert-file() option. When establishing TLS connection, syslog-ng OSE authenticates on the Riemann server using this private key and the matching certificate set in the cert-file() option.

Note that you have to set the cert-file() and key-file() options only if the Riemann server requires authentication from the clients.

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")
	)

This option was called key() in syslog-ng OSE version 3.7.