System Logging

TODO: {{#todo: InProgress (04.13.2015-14:44->BS+)(11.10.2015-18:00->MD+)(11.11.2015-10:30->MD+)|Mike Dean|OE 5.0,BS,MD}}

This document provides an overview of how system logging works in Linux, and provides guidance on how to work with and configure system logging so that it meets your needs.

Background

System Logging services exist on Linux systems to provide a central logging facility. This central logging service can store logged messages in files on the local machine, can forward the log messages to a remote machine for remote storage and display, and can output the log messages as they arrive to a terminal.

The syslog facility is standardized by POSIX and, as a result, there is a great deal of support for the syslog facility. There are APIs for logging to the syslog facility from C, C++, Python, Java, PHP, Perl, Bash, the commandline, and many other languages. Using the commandline tool, it is even possible to write to the syslog facility from the commandline.

Facilities

In syslog terminology, a facility is a category for log messages. There are generally at least seven standard syslog facilities on any Linux syslog system. The following list shows the standard seven as well as some which are rarely used anymore (especially in embedded systems). The name of the facility is followed, in parenthesis, by the integer facility code associated with the facility, which is then followed by a description of the facility. The ones you should not expect to find on an embedded system are demarcated with an asterisk (*):

kern(0)

Kernel messages

user(1)

User Level Messages

mail(2)*

Mail System Messages

daemon(3)

System Daemon Messages

auth(4)

Security/Authentication Messages

syslog(5)

Internally Generated Syslog Messages

lpr(6)*

Line Printer Subsystem Messages

news(7)*

Network News Subsystem Messages

uucp(8)*

UUCP Subsystem Messages

cron(15)

Cron Scheduling Daemon Messages

local(16-23)

Locally Defined Usage, Messages

Severity

Each of these facilities accepts messages which will have an associated severity level. The severity level is important for filtering messages. The following list shows the eight available severity levels:

emerg(0)

Emergency - System is now unusable

alert(1)

Alert - Immediate Attention is Required

crit(2)

Critical - The System is in a Critical Condition, which may be caused by a failure in the primary appliction.

err(3)

Error - An Error has occurred.

warning(4)

Warning - An unusual, but not erroneous, event has occurred. For example: "Warning: Could not check for updates."

notice(5)

Notice - Uncommon but generally expected messages. For example: "Network Interface eth0 received IP address of 192.168.0.100 from DHCP server."

info(6)

Informational - Common, expected events generate these messages. For example: "Application XYZ started successfully."

debug(7)

Debug - Debugging messages belong at this level.

Storage

By default, the log messages on an EMAC OE Linux machine are stored in a local ramdisk. This type of storage prevents excessive wear of the flash, and works when all of the flash partitions are mounted read-only. However, by storing the messages in a ramdisk, all messages in the ramdisk will be lost as soon as the machine resets, powers off, or reboots for any reason.

Alternate Logging Locations

The syslog server can be configured to log to alternate locations. This is useful for configuring the server to log to persistent storage, such as a writable partition on the local flash or a partition on an SD card. The alternate logging locations can even be remote machines.

Remote Logging

The /var/log directory is the standard location for holding local log messages. This directory usually contains either one file per facility or one directory per facility. If a facility has a directory, it may contain different files which all belong to the facility. The system logging facility directs messages to these files based on rules set in its configuration. The configured rules use the facility level and the severity level to direct the syslogger's filters regarding to which file to send any particular message. There are several different implementations of the syslogger facility, each with its own configuration mechanisms and level of flexibility.

The system logger is also able to send messages to a remote syslog server over a network. The remote syslog server will be able to filter the messages using all of the same criteria as above, but also by source. A remote syslog server configuration can be very useful for remotely debugging deployed machines. While an embedded machine stores its logs on a ramdisk, the remote machine may store them to a traditional hard disk or SSD, allowing them to be preserved through power cycles.

The remote syslog server can be on any normal server, it can be on a developer's desktop, or it can be on another embedded machine. Sending debug messages to a central syslog server ensures the debug messages will be available even if the machine of interest freezes or resets. The use of a remote syslog server can also assist with looking for trends and outliers among a group of deployed machines since the log messages for the entire group of machines can be located in one place.

Log Rotation

Syslog servers incorporate a feature called log rotation. Log rotation is a process which prevents log files from growing beyond a certain size while preserving log messages for later reference. The syslog server (or logrotate system) can be configured with a maximum file size and a maximum number of rotated logs to keep. When the maximum file size is reached, the file will be "rotated." When the maximum number of logs to keep is exceeded, the oldest one will be deleted. There is more information on how this process works below.

General Information

Your Daemons

When developing a software daemon, syslog is a very useful tool for monitoring and debugging your software. The syslog daemon is highly configurable, allowing filters to be altered to suit the current needs of a developer without recompiling software. This capability allows developers to deploy software which sends ample debugging messages to the syslog server without fear of overwhelming the system with debug messages. Using the eight local facilities syslog recognizes, these debug messages can be categorized by developers to allow them to selectively choose the amount of log information they store from each of up to eight different subsystems. This is extremely useful when a system in the field is experiencing intermittent issues. By enabling maximum debugging output for only the subsystem responsible for the feature which is misbehaving, the developers have the greatest chance of seeing the messages they need to diagnose the source of the problem without overwhelming the system (or the storage) with messages. If eight facilities is not enough, the developers can always repurpose dedicated facilities which aren't in use by their intended systems. For instance, the line printing facility is rarely used on an embedded system, and may be safely repurposed by developers.

Web Development

When providing a web interface for an embedded system, the syslog daemon is often the only way to debug a variety of issues with the web server. When links don't work, certain browsers have issues, pages load slowly, or any of a myriad of other issues crop up, the logs are generally the first place people turn for answers. This is just as true on embedded systems as it is on any large scale web server or server farm. On embedded systems, however, the configuration for the logging system may need to be altered due to the volatile nature of the logs in the default configuration. This document provides information on how to solve the issues which may be encountered as a result of this.

Machine Startup

When configuring a machine to start up all the necessary services in the correct sequential order, when the machine is powered on, the syslog server is very helpful in performing the following tasks:

• Ensuring that process X really did start before process Y.
• Checking to see if any errors or warnings were reported by processes starting up.
• Ensuring that processes really did start, at all.
• Checking to see what configuration was chosen by a process which is capable of choosing its configuration dynamically.
• Checking the messages reported by device drivers as they start up.
• Determining the IP address used by a system which gets its network configuration via DHCP.

Startup scripts log their activity to the syslog daemon. Any daemon process launched by these startup scripts should also log startup messages to indicate that they're starting, how they're configured, and that they've finished the startup sequence and are now running. The system logs enable the engineer to assure that a machine has started as intended.

Malfunctioning Systems

When a proven system is malfunctioning, the system logs can be essential in determining the cause of the malfunction. In cases such as this, the system logs are helpful for:

• Looking to see who logged into a machine, and when.
• Looking for signs of attacks directed at the machine.
• Looking for signs of failing hardware.
• Looking for error and warning messages coming from system processes, daemons, and/or your custom application.

Without these logs, it may be nearly impossible to diagnose these malfunctions.

In Brief

This guide provides enough background information to enable you to handle any of the situations described above. Using the information contain herein, you will be able to approach any of the above listed problems with the tools you need to solve the problems you are facing.

NOTE

To make best use of the log files, a working knowledge of grep is highly beneficial. Experience with crafting and using regular expressions with grep prior to writing system logging messages in your application and init scripts can make the diagnosis process simpler, since a little forethought into a syntax for the messages can make filtering the messages through grep much easier to accomplish correctly.

System Logging

EMAC OE Linux 5.0 uses Busybox's syslog daemon, syslogd, by default. However, the syslog-ng package can be installed to provide a much more capable system logging daemon, when needed.

Default Syslog Daemon

The Busybox syslog daemon is configured to log to files in the RAMDISK mounted on /var/log/. The files contained in this directory will be capped in size and rotated according to the configuration of the syslog daemon. The standard syslog daemon supports the following configuration capabilities:

• Maximum size limit for log files.
• Maximum number of log files to keep, when rotated.
• Minimum priority level for messages to log.
• Duplicate dropping (not usually recommended).
• Log to remote and local files simultaneously, just to local files, or to a memory buffer which needs to be read by a special utility.

Optional syslog-ng With logrotate

The optional syslog-ng and logrotate option provides everything that's provided by the Busybox syslog daemon, plus:

• Sophisticated filters for directing log traffic.
• The ability to act as a central syslog server which receives log messages from remote syslog machines.
• Enhanced control over the destination(s) for log messages, allowing (for example) messages to be logged to a local RAMDISK, a local SD card (if available), and to a remote syslog server (if available) simultaneously.
• The ability to configure logrotate to automatically e-mail log files when they're rotated.

• Same syslog server software is readily available for Linux desktops and servers.

As can be expected, the potential drawback of syslog-ng is the steeper learning curve required to make use of its more sophisticated features. However, those already familiar with syslog-ng will be able to benefit from its extra sophistication immediately.

The official manual page for syslog-ng has more details: http://www.syslog.org/syslog-ng/v1/

Please contact EMAC for details on how to install syslog-ng and logrotate if you have trouble finding and installing them with opkg.

Examples

Evaluating Log Messages

Log messages are stored in /var/log/ by default. This directory contains at least one log file, messages.

Writing to Syslog from Programs and Scripts

As mentioned previously, many languages support writing to the Linux system logging utility.