The stomp() driver sends messages to servers (message brokers) using the Simple (or Streaming) Text Oriented Message Protocol (STOMP), formerly known as TTMP. syslog-ng PE supports version 1.0 of the STOMP protocol. The syslog-ng PE stomp() driver supports persistence.

The name-value pairs selected with the value-pairs() option will be sent as STOMP headers, while the body of the STOMP message is empty by default (but you can add custom content using the body() option). Publishing the name-value pairs as headers makes it possible to use the Headers exchange-type and subscribe only to interesting log streams. This solution is more flexible than using the routing-key() option.

For the list of available parameters, see stomp() destination options.

Declaration:
stomp( host("<stomp-server-address>") );
Example: Using the stomp() driver

The following example shows the default values of the available options.

destination d_stomp {
    stomp(
        host("localhost")
        port(61613)
        destination("/topic/syslog")
        routing-key("")      # optional, empty by default
        body("")             # optional, empty by default
        persistent(yes)
        ack(no)
        username("user")     # optional, empty by default
        password("password") # optional, empty by default
        value-pairs(scope(selected-macros, nv-pairs, sdata))
    );
};
stomp() destination options

The stomp() driver publishes messages using the Simple (or Streaming) Text Oriented Message Protocol (STOMP).

The stomp() destination has the following options:

ack()
Type: yes|no
Default: no

Description: Request the STOMP server to acknowledge the receipt of the messages. If you enable this option, then after sending a message, syslog-ng PE waits until the server confirms that it has received the message. This delay can seriously limit the performance of syslog-ng PE if the message rate is high, and the server cannot acknowledge the messages fast enough.

body()
Type: string
Default: empty string

Description: The body of the STOMP message. You can also use macros and templates.

destination()
Type: string
Default: /topic/syslog

Description: The name of the destination (message queue) on the STOMP server. It can include macros and templates.

disk-buffer()

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

dir()
Type: string
Default: N/A

Description: Defines the folder where the disk-buffer files are stored.

Note that changing the value the dir() option will not move or copy existing files from the old directory to the new one.

 Caution:

When creating a new dir() option for a disk-buffer file, or modifying an existing one, make sure you delete the persist file.

syslog-ng PE creates disk-buffer files based on the path recorded in the persist file. Therefore, if the persist file is not deleted after modifying the dir() option, then following a restart, syslog-ng PE will look for or create disk-buffer files in their old location. To ensure that syslog-ng PE uses the new dir() setting, the persist file must not contain any information about the destinations which the disk-buffer file in question belongs to.
disk-buf-size()
Type: number [bytes]
Default:

Description: This is a required option. The maximum size of the disk-buffer file 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 file. 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.
quot-size()
Type: number [messages]
Default: 1000

Description: The number of messages stored in the output buffer of the destination. Note that if you change the value of this option and the disk-buffer file already exists, the change will take effect when the disk-buffer file becomes empty.
reliable()
Type: yes|no
Default: no

Description: If set to yes, syslog-ng PE cannot lose logs in case of reload/restart, unreachable destination or syslog-ng PE 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 option will be used. This provides a faster, but less reliable disk-buffer option.

 Caution: Hazard of data loss!

If you change the value of reliable() option when there are messages in the disk-buffer file, the messages stored in the disk-buffer file will be lost.
truncate-size-ratio()
Type: number (for percentage) between 0 and 1
Default: 0.1 (10%)

Description: Limits the truncation of the disk-buffer file. Truncating the disk-buffer file can slow down disk I/O operations, but it saves disk space. As a result, syslog-ng PE only truncates the file if the possible disk gain is more than truncate-size-ratio() times disk-buf-size().

 Caution:

One Identity recommends that you do not modify the value of the truncate-size-ratio() option unless you are fully aware of the potential performance implications.
Example: 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")
        )
    );
};
host()
Type: hostname or IP address
Default: 127.0.0.1

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

password()
Type: string
Default: n/a

Description: The password used to authenticate on the STOMP server.

persistent()
Type: yes|no
Default: yes

Description: If this option is enabled, the STOMP server or broker will store the messages on its hard disk. That way, the messages will be retained if the STOMP server is restarted, if the message queue is set to be durable on the STOMP server.

port()
Type: number
Default: 61613

Description: The port number of the STOMP server.

retries()
Type: number [of attempts]
Default: 3

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

routing-key()
Type: string
Default: empty string

Description: Specifies a routing key for the exchange. The routing key selects certain messages published to an exchange to be routed to the bound queue. In other words, the routing key acts like a filter. The routing key can include macros and templates.

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 the disk-buffer option as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.

username()
Type: string
Default: empty string

Description: The username used to authenticate on the STOMP server.

value-pairs()
Type: parameter list of the value-pairs() option
Default: 
scope("selected-macros" "nv-pairs")

Description: The value-pairs() option creates structured name-value pairs from the data and metadata of the log message. For details on using value-pairs(), see Structuring macros, metadata, and other value-pairs.

NOTE: Empty keys are not logged.