Chat now with support
Chat with Support

syslog-ng Premium Edition 6.0.18 - Administration Guide

Preface Chapter 1. Introduction to syslog-ng Chapter 2. The concepts of syslog-ng Chapter 3. Installing syslog-ng Chapter 4. The syslog-ng PE quick-start guide Chapter 5. The syslog-ng PE configuration file Chapter 6. Collecting log messages — sources and source drivers Chapter 7. Sending and storing log messages — destinations and destination drivers Chapter 8. Routing messages: log paths, reliability, and filters Chapter 9. Global options of syslog-ng PE Chapter 10. TLS-encrypted message transfer Chapter 11. FIPS-compliant syslog-ng Chapter 12.  Reliable Log Transfer Protocol™ Chapter 13. Reliability and minimizing the loss of log messages Chapter 14. Manipulating messages Chapter 15. Parsing and segmenting structured messages Chapter 16. Processing message content with a pattern database Chapter 17. Statistics and metrics of syslog-ng Chapter 18. Multithreading and scaling in syslog-ng PE Chapter 19. Troubleshooting syslog-ng Chapter 20. Best practices and examples

Optimizing multithreaded performance

Sources: 

In syslog-ng, every source has a reader thread. To improve scaling on the source side, use multiple sources instead of one.

For example, if you are using a file source with a wildcard character (such as *.txt), syslog-ng will monitor every matching file (and keep switching between them), but will use only one thread. It is best to configure several single file sources (such as file source1, file source2, and so on) that all monitor only a single file or a smaller range of files. In this case, every file source will use its own thread.

TCP-based network sources form an exception: a TCP-based network source will scale based on the number of active connections. This means that if there are 10 incoming TCP connections all coming to the same network source, then that source can use 10 threads, one thread for each connection.

NOTE:

UDP-based network sources do not scale by themselves because they always use a single thread. If you want to handle a large number of UDP connections, it is best to configure a subset of your clients to send the messages to a different port of your syslog-ng server, and use separate source definitions for each port.

Figure 18.1. How multithreading works — sources

How multithreading works — sources

Message processors: 

Message processors — such as filters, rewrite rules, and parsers — are executed by the reader thread in a sequential manner.

For example, if you have a log path that defines two sources and a filter, the filter will be performed by the source1 reader thread when log messages come from source1, and by the source2 reader thread when log messages come from source2. This means that if log messages come from both source1 and source2, they will both have a reader thread and that way filtering will be performed simultaneously.

NOTE:

This is not true for PatternDB because it uses message correlation. When using PatternDB, it runs in only one thread at a time, and this significantly decreases performance.

Destinations: 

In syslog-ng, every destination has a writer thread. To improve scaling on the destination side, use multiple destinations instead of one.

For example, when sending messages to a syslog-ng server, you can use multiple connections to the server if you configure the syslog-ng server to receive messages on multiple ports, and configure the clients to use both ports.

When writing the log messages to files, use macros in the filename to split the messages to separate files (for example, using the ${HOST} macro). Files with macros in their filenames are processed in separate writer threads.

Figure 18.2. How multithreading works — destinations

How multithreading works — destinations

Chapter 19. Troubleshooting syslog-ng

This chapter provides tips and guidelines about troubleshooting problems related to syslog-ng. Troubleshooting the syslog-ng Agent for Windows application is discussed in Administration Guide for syslog-ng Agent for Windows.

  • As a general rule, first try to get logging the messages to a local file. Once this is working, you know that syslog-ng is running correctly and receiving messages, and you can proceed to forwarding the messages to the server.

  • Always check the configuration files for any syntax errors on both the client and the server using the syslog-ng --syntax-only command.

  • If the syslog-ng PE server does not receive the messages, verify that the IP addresses and ports are correct in your sources and destinations. Also, check that the client and the server uses the same protocol (a common error is to send logs on UDP, but configure the server to receive logs on TCP.

    If the problem persist, use tcpdump or a similar packet sniffer tool on the client to verify that the messages are sent correctly, and on the server to verify that it receives the messages.

  • To find message-routing problems, run syslog-ng PE with the following command syslog-ng -Fevd. That way syslog-ng PE will run in the foreground, and display debug messages about the messages that are processed.

  • If syslog-ng is closing the connections for no apparent reason, be sure to check the log messages of syslog-ng. You might also want to run syslog-ng with the --verbose or --debug command-line options for more-detailed log messages. You can enable these messages without restarting syslog-ng using the syslog-ng-ctl verbose --set=on command. For details, see the syslog-ng-ctl man page at syslog-ng-ctl(1).

  • Build up encrypted connections step-by-step: first create a working unencrypted (for example TCP) connection, then add TLS encryption, and finally client authentication if needed.

  • If you use the same driver and options in the destination of your syslog-ng PE client and the source of your syslog-ng PE server, everything should work as expected. Unfortunately there are some other combinations, that seem to be working, but result in losing parts of the messages. For details on the working combinations, see the section called “Things to consider when forwarding messages between syslog-ng PE hosts”.

Possible causes of losing log messages

During the course of a message from the sending application to the final destination of the message, there are a number of locations where a message may be lost, even though syslog-ng does its best to avoid message loss. Usually losing messages can be avoided with careful planning and proper configuration of syslog-ng and the hosts running syslog-ng. The following list shows the possible locations where messages may be lost, and provides methods to minimize the risk of losing messages.

NOTE:

The following list covers the main possibilities of losing messages, but does not take into account the possible use of flow-control (for details, see the section called “Managing incoming and outgoing messages with flow-control”).

If your syslog-ng PE host uses an NFS partition, see the section called “NFS file system for log files”.

  • Between the application and the syslog-ng client: Make sure to use an appropriate source to receive the logs from the application (for example from /dev/log). For example, use unix-stream instead of unix-dgram whenever possible.

  • When syslog-ng is sending messages: If syslog-ng cannot send messages to the destination and the output buffer gets full, syslog-ng will drop messages. Use flags (flow-control) to avoid it (for details, see the section called “Configuring flow-control”). The number of dropped messages is displayed per destination in the log message statistics of syslog-ng (for details, see Chapter 17, Statistics and metrics of syslog-ng).

  • On the network: When transferring messages using the UDP protocol, messages may be lost without any notice or feedback — such is the nature of the UDP protocol. Always use the TCP protocol to transfer messages over the network whenever possible.

    For details on minimizing message loss when using UDP, see the following tutorial: Collecting log messages from UDP sources.

  • In the socket receive buffer: When transferring messages using the UDP protocol, the UDP datagram (that is, the message) that reaches the receiving host placed in a memory area called the socket receive buffer. If the host receives more messages than it can process, this area overflows, and the kernel drops messages without letting syslog-ng know about it. Using TCP instead of UDP prevents this issue. If you must use the UDP protocol, increase the size of the receive buffer using the so-rcvbuf() option.

  • When syslog-ng is receiving messages:

    • The receiving syslog-ng (for example the syslog-ng server or relay) may drop messages if the fifo of the destination file gets full. The number of dropped messages is displayed per destination in the log message statistics of syslog-ng (for details, see Chapter 17, Statistics and metrics of syslog-ng).

    • If the number of Log Source Hosts reaches the license limit, the syslog-ng PE server will not accept connections from additional hosts. The messages sent by additional hosts will be dropped, even if the client uses a reliable transport method (for example, RLTP).

  • When the destination cannot handle large load: When syslog-ng is sending messages at a high rate into an SQL database, a file, or another destination, it is possible that the destination cannot handle the load, and processes the messages slowly. As a result, the buffers of syslog-ng fill up, syslog-ng cannot process the incoming messages, and starts to loose messages. For details, see the previous entry. Use the throttle parameter to avoid this problem.

  • As a result of an unclean shutdown of the syslog-ng server: If the host running the syslog-ng server experiences an unclean shutdown, it takes time until the clients realize that the connection to the syslog-ng server is down. Messages that are put into the output TCP buffer of the clients during this period are not sent to the server.

  • When syslog-ng PE is writing messages into files: If syslog-ng PE receives a signal (SIG) while writing log messages to file, the log message that is processed by the write call can be lost if the flush_lines parameter is higher than 1.

  • When using the RLTP™ protocol:

    In the following cases, it is possible to lose log messages even if you use RLTP™:

    • If you use RLTP™ together with non-reliable disk-buffer, it is possible to lose logs.

    • When sending logs through a relay that is using a non-reliable disk-buffer, it is possible to lose logs if the relay crashes.

    • When sending logs through a relay that is using a non-reliable disk-buffer, it is possible that logs are duplicated if the relay crashes, or it is stopped.

    • If the underlying disk system of syslog-ng PE fails to write the log messages to the disk, but it does not return a write error, or some other hardware or operating-system error happens.

      NOTE:

      To minimize the chances of losing messages, it is recommended to set the flush-size() parameter of the receiver to 1 (however, note that depending on your syslog-ng PE configuration, this can decrease the performance of the receiver).

Procedure 19.1. Creating syslog-ng core files

Purpose: 

When syslog-ng crashes for some reason, it can create a core file that contains important troubleshooting information. To enable core files, complete the following procedure:

Steps: 

  1. Core files are produced only if the maximum core file size ulimit is set to a high value in the init script of syslog-ng.Add the following line to the init script of syslog-ng:

    ulimit -c unlimited
  2. Verify that syslog-ng has permissions to write the directory it is started from, for example /opt/syslog-ng/sbin/.

  3. If syslog-ng crashes, it will create a core file in the directory syslog-ng was started from.

  4. To test that syslog-ng can create a core file, you can create a crash manually. For this, determine the PID of syslog-ng (for example using the ps -All|grep syslog-ng command), then issue the following command: kill -ABRT <syslog-ng pid>

    This should create a core file in the current working directory.

Procedure 19.2. Running a failure script

Purpose: 

You can create a failure script that is executed when syslog-ng PE terminates abnormally, that is, when it exits with a non-zero exit code. For example, you can use this script to send an automatic e-mail notification.

Prerequisites: 

The failure script must be the following file: /opt/syslog-ng/sbin/syslog-ng-failure, and must be executable.

To create a sample failure script, complete the following steps.

Steps: 

  1. Create a file named /opt/syslog-ng/sbin/syslog-ng-failure with the following content:

    #!/usr/bin/env bash
    cat >>/tmp/test.txt <<EOF
    $(date)
    Name............$1
    Chroot dir......$2
    Pid file dir....$3
    Pid file........$4
    Cwd.............$5
    Caps............$6
    Reason..........$7
    Argbuf..........$8
    Restarting......$9
    
    EOF
  2. Make the file executable: chmod +x /opt/syslog-ng/sbin/syslog-ng-failure

  3. Run the following command in the /opt/syslog-ng/sbin directory: ./syslog-ng --process-mode=safe-background; sleep 0.5; ps aux | grep './syslog-ng' | grep -v grep | awk '{print $2}' | xargs kill -KILL; sleep 0.5; cat /tmp/test.txt

    The command starts syslog-ng PE in safe-background mode (which is needed to use the failure script) and then kills it. You should see that the relevant information is written into the /tmp/test.txt file, for example:

    Thu May 18 12:08:58 UTC 2017
    Name............syslog-ng
    Chroot dir......NULL
    Pid file dir....NULL
    Pid file........NULL
    Cwd.............NULL
    Caps............NULL
    Reason..........signalled
    Argbuf..........9
    Restarting......not-restarting
  4. You should also see messages similar to the following in system syslog. The exact message depends on the signal (or the reason why syslog-ng PE stopped):

    May 18 13:56:09 myhost supervise/syslog-ng[10820]: Daemon exited gracefully, not restarting; exitcode='0'
    May 18 13:57:01 myhost supervise/syslog-ng[10996]: Daemon exited due to a deadlock/signal/failure, restarting; exitcode='131'
    May 18 13:57:37 myhost supervise/syslog-ng[11480]: Daemon was killed, not restarting; exitcode='9'

    The failure script should run on every non-zero exit event.

Collecting debugging information with strace, truss, or tusc

To properly troubleshoot certain situations, it can be useful to trace which system calls syslog-ng PE performs. How this is performed depends on the platform running syslog-ng PE. In general, note the following points:

  • When syslog-ng PE is started, a supervisor process might stay in the foreground, while the actual syslog-ng daemon goes to the background. Always trace the background process.

  • Apart from the system calls, the time between two system calls can be important as well. Make sure that your tracing tool records the time information as well. For details on how to do that, refer to the manual page of your specific tool (for example, strace on Linux, or truss on Solaris and BSD).

  • Run your tracing tool in verbose mode, and if possible, set it to print long output strings, so the messages are not truncated.

  • When using strace, also record the output of lsof to see which files are accessed.

The following are examples for tracing system calls of syslog-ng on some platforms. The output is saved into the /tmp/syslog-ng-trace.txt file, sufficed with the PID of the related syslog-ng process.The path of the syslog-ng binary assumes that you have installed syslog-ng PE from the official syslog-ng PE binaries available at the BalaBit website — native distribution-specific packages may use different paths.

  • Linux: strace -o /tmp/trace.txt -s256 -ff -ttT /opt/syslog-ng/sbin/syslog-ng -f /opt/syslog-ng/etc/syslog-ng.conf -Fdv

  • HP-UX: tusc -f -o /tmp/syslog-ng-trace.txt -T /opt/syslog-ng/sbin/syslog-ng

  • IBM AIX and Solaris: truss -f -o /tmp/syslog-ng-trace.txt -r all -w all -u libc:: /opt/syslog-ng/sbin/syslog-ng -d -d -d

TIP:

To execute these commands on an already running syslog-ng PE process, use the -p <pid_of_syslog-ng> parameter.

Stopping syslog-ng

To avoid problems, always use the init scripts to stop syslog-ng (/etc/init.d/syslog-ng stop), instead of using the kill command. This is especially true on Solaris and HP-UX systems, here use /etc/init.d/syslog stop.

Related Documents