System logging functions

The log module provides bindings to the POSIX syslog functions openlog(), syslog() and closelog() as well as - when available - the OpenWrt specific ulog library functions.

Functions can be individually imported and directly accessed using the named import syntax:

import { openlog, syslog, LOG_PID, LOG_USER, LOG_ERR } from 'log';

openlog("my-log-ident", LOG_PID, LOG_USER);
syslog(LOG_ERR, "An error occurred!");

// OpenWrt specific ulog functions
import { ulog_open, ulog, ULOG_SYSLOG, LOG_DAEMON, LOG_INFO } from 'log';

ulog_open(ULOG_SYSLOG, LOG_DAEMON, "my-log-ident");
ulog(LOG_INFO, "The current epoch is %d", time());

Alternatively, the module namespace can be imported using a wildcard import statement:

import * as log from 'log';

log.openlog("my-log-ident", log.LOG_PID, log.LOG_USER);
log.syslog(log.LOG_ERR, "An error occurred!");

// OpenWrt specific ulog functions
log.ulog_open(log.ULOG_SYSLOG, log.LOG_DAEMON, "my-log-ident");
log.ulog(log.LOG_INFO, "The current epoch is %d", time());

Additionally, the log module namespace may also be imported by invoking the ucode interpreter with the -llog switch.

Constants

The log module declares a number of numeric constants to specify logging facility, priority and option values, as well as ulog specific channels.

Syslog Options

Constant NameDescription
LOG_PIDInclude PID with each message.
LOG_CONSLog to console if error occurs while sending to syslog.
LOG_NDELAYOpen the connection to the logger immediately.
LOG_ODELAYDelay open until the first message is logged.
LOG_NOWAITDo not wait for child processes created during logging.

Syslog Facilities

Constant NameDescription
LOG_AUTHAuthentication/authorization messages.
LOG_AUTHPRIVPrivate authentication messages.
LOG_CRONClock daemon (cron and at commands).
LOG_DAEMONSystem daemons without separate facility values.
LOG_FTPFTP server daemon.
LOG_KERNKernel messages.
LOG_LPRLine printer subsystem.
LOG_MAILMail system.
LOG_NEWSNetwork news subsystem.
LOG_SYSLOGMessages generated internally by syslogd.
LOG_USERGeneric user-level messages.
LOG_UUCPUUCP subsystem.
LOG_LOCAL0Local use 0 (custom facility).
LOG_LOCAL1Local use 1 (custom facility).
LOG_LOCAL2Local use 2 (custom facility).
LOG_LOCAL3Local use 3 (custom facility).
LOG_LOCAL4Local use 4 (custom facility).
LOG_LOCAL5Local use 5 (custom facility).
LOG_LOCAL6Local use 6 (custom facility).
LOG_LOCAL7Local use 7 (custom facility).

Syslog Priorities

Constant NameDescription
LOG_EMERGSystem is unusable.
LOG_ALERTAction must be taken immediately.
LOG_CRITCritical conditions.
LOG_ERRError conditions.
LOG_WARNINGWarning conditions.
LOG_NOTICENormal, but significant, condition.
LOG_INFOInformational message.
LOG_DEBUGDebug-level message.

Ulog channels

Constant NameDescription
ULOG_KMSGLog messages to /dev/kmsg (dmesg).
ULOG_STDIOLog messages to stdout.
ULOG_SYSLOGLog messages to syslog.

Methods

ERR(format, …argsopt) → {boolean}

Invoke ulog with LOG_ERR.

This function is convenience wrapper for ulog(LOG_ERR, ...).

See ulog() for details.

Parameters:
NameTypeDescription
format*

The sprintf-like format string for the log message, or any other, non-null, non-string value type which will be implicitly stringified and logged as-is.

args*(optional, repeatable)

In case a format string value was provided in the previous argument, then all subsequent arguments are used to replace the placeholders in the format string.

Returns: boolean
Example
ERR("This is an error!");

INFO(format, …argsopt) → {boolean}

Invoke ulog with LOG_INFO.

This function is convenience wrapper for ulog(LOG_INFO, ...).

See ulog() for details.

Parameters:
NameTypeDescription
format*

The sprintf-like format string for the log message, or any other, non-null, non-string value type which will be implicitly stringified and logged as-is.

args*(optional, repeatable)

In case a format string value was provided in the previous argument, then all subsequent arguments are used to replace the placeholders in the format string.

Returns: boolean
Example
INFO("This is an info log message");

NOTE(format, …argsopt) → {boolean}

Invoke ulog with LOG_NOTICE.

This function is convenience wrapper for ulog(LOG_NOTICE, ...).

See ulog() for details.

Parameters:
NameTypeDescription
format*

The sprintf-like format string for the log message, or any other, non-null, non-string value type which will be implicitly stringified and logged as-is.

args*(optional, repeatable)

In case a format string value was provided in the previous argument, then all subsequent arguments are used to replace the placeholders in the format string.

Returns: boolean
Example
NOTE("This is a notification log message");

WARN(format, …argsopt) → {boolean}

Invoke ulog with LOG_WARNING.

This function is convenience wrapper for ulog(LOG_WARNING, ...).

See ulog() for details.

Parameters:
NameTypeDescription
format*

The sprintf-like format string for the log message, or any other, non-null, non-string value type which will be implicitly stringified and logged as-is.

args*(optional, repeatable)

In case a format string value was provided in the previous argument, then all subsequent arguments are used to replace the placeholders in the format string.

Returns: boolean
Example
WARN("This is a warning");

closelog()

Close connection to system logger.

The usage of this function is optional, and usually an explicit log connection tear down is not required.

openlog(identopt, optionsopt, facilityopt) → {boolean}

Open connection to system logger.

The openlog() function instructs the program to establish a connection to the system log service and configures the default facility and identification for use in subsequent log operations. It may be omitted, in which case the first call to syslog() will implicitly call openlog() with a default ident value representing the program name and a default LOG_USER facility.

The log option argument may be either a single string value containing an option name, an array of option name strings or a numeric value representing a bitmask of LOG_* option constants.

The facility argument may be either a single string value containing a facility name or one of the numeric LOG_* facility constants in the module namespace.

Returns true if the system openlog() function was invoked.

Returns false if an invalid argument, such as an unrecognized option or facility name, was provided.

Parameters:
NameTypeDescription
identstring(optional)

A string identifying the program name. If omitted, the name of the calling process is used by default.

optionsnumber | LogOption | LogOption[](optional)

Logging options to use.

See LogOption for recognized option names.

facilitynumber | LogFacility(optional, default: "user")

The facility to use for log messages generated by subsequent syslog calls.

See LogFacility for recognized facility names.

Returns: boolean
Example
// Example usage of openlog function
openlog("myapp", LOG_PID | LOG_NDELAY, LOG_LOCAL0);

// Using option names instead of bitmask and LOG_USER facility
openlog("myapp", [ "pid", "ndelay" ], "user");

syslog(priority, format, …argsopt) → {boolean}

Log a message to the system logger.

This function logs a message to the system logger. The function behaves in a sprintf-like manner, allowing the use of format strings and associated arguments to construct log messages.

If the openlog function has not been called explicitly before, syslog() implicitly calls openlog(), using a default ident and LOG_USER facility value before logging the message.

If the format argument is not a string and not null, it will be implicitly converted to a string and logged as-is, without further format string processing.

Returns true if a message was passed to the system syslog() function.

Returns false if an invalid priority value or an empty message was given.

Parameters:
NameTypeDescription
prioritynumber | LogPriority

Log message priority. May be either a number value (potentially bitwise OR-ed with a log facility constant) which is passed as-is to the system syslog() function or a priority name string.

See LogPriority for recognized priority names.

format*

The sprintf-like format string for the log message, or any other, non-null, non-string value type which will be implicitly stringified and logged as-is.

args*(optional, repeatable)

In case a format string value was provided in the previous argument, then all subsequent arguments are used to replace the placeholders in the format string.

Returns: boolean
Example
// Example usage of syslog function with format string and arguments
const username = "user123";
const errorCode = 404;
syslog(LOG_ERR, "User %s encountered error: %d", username, errorCode);

// If openlog has not been called explicitly, it is implicitly called with defaults:
syslog(LOG_INFO, "This message will be logged with default settings.");

// Selectively override used facility by OR-ing numeric constant
const password =" secret";
syslog(LOG_DEBUG|LOG_AUTHPRIV, "The password %s has been wrong", secret);

// Using priority names for logging
syslog("emerg", "System shutdown imminent!");

// Implicit stringification
syslog("debug", { foo: 1, bar: true, baz: [1, 2, 3] });

ulog(priority, format, …argsopt) → {boolean}

Log a message via the ulog mechanism.

The ulog() function outputs the given log message to all configured ulog channels unless the given priority level exceeds the globally configured ulog priority threshold. See ulog_threshold() for details.

The ulog() function is OpenWrt specific and may not be present on other systems. Use syslog() instead for portability to non-OpenWrt environments.

Like syslog(), the function behaves in a sprintf-like manner, allowing the use of format strings and associated arguments to construct log messages.

If the ulog_open() function has not been called explicitly before, ulog() implicitly configures certain defaults, see ulog_open() for a detailled description.

If the format argument is not a string and not null, it will be implicitly converted to a string and logged as-is, without further format string processing.

Returns true if a message was passed to the underlying ulog() function.

Returns false if an invalid priority value or an empty message was given.

Parameters:
NameTypeDescription
prioritynumber | LogPriority

Log message priority. May be either a number value or a priority name string.

See LogPriority for recognized priority names.

format*

The sprintf-like format string for the log message, or any other, non-null, non-string value type which will be implicitly stringified and logged as-is.

args*(optional, repeatable)

In case a format string value was provided in the previous argument, then all subsequent arguments are used to replace the placeholders in the format string.

Returns: boolean
Example
// Example usage of ulog function with format string and arguments
const username = "user123";
const errorCode = 404;
ulog(LOG_ERR, "User %s encountered error: %d", username, errorCode);

// Using priority names for logging
ulog("err", "General error encountered");

// Implicit stringification
ulog("debug", { foo: 1, bar: true, baz: [1, 2, 3] });

ulog_close()

Close ulog logger.

Resets the ulog channels, the default facility and the log ident value to defaults.

In case the "syslog" channel has been configured, the underlying closelog() function will be invoked.

The usage of this function is optional, and usually an explicit ulog teardown is not required.

The ulog_close() function is OpenWrt specific and may not be present on other systems. Use closelog() in conjunction with syslog() instead for portability to non-OpenWrt environments.

ulog_open(channelopt, facilityopt, identopt) → {boolean}

Configure ulog logger.

This functions configures the ulog mechanism and is analogeous to using the openlog() function in conjuncton with syslog().

The ulog_open() function is OpenWrt specific and may not be present on other systems. Use openlog() and syslog() instead for portability to non-OpenWrt environments.

A program may use multiple channels to simultaneously output messages using different means. The channel argument may either be a single string value containing a channel name, an array of channel names or a numeric value representing a bitmask of ULOG_* channel constants.

The facility argument may be either a single string value containing a facility name or one of the numeric LOG_* facility constants in the module namespace.

The default facility value varies, depending on the execution context of the program. In OpenWrt's preinit boot phase, or when stdout is not connected to an interactive terminal, the facility defaults to "daemon" (LOG_DAEMON), otherwise to "user" (LOG_USER).

Likewise, the default channel is selected depending on the context. During OpenWrt's preinit boot phase, the "kmsg" channel is used, for interactive terminals the "stdio" one and for all other cases the "syslog" channel is selected.

Returns true if ulog was configured.

Returns false if an invalid argument, such as an unrecognized channel or facility name, was provided.

Parameters:
NameTypeDescription
channelnumber | UlogChannel | UlogChannel[](optional)

Specifies the log channels to use.

See UlogChannel for recognized channel names.

facilitynumber | LogFacility(optional)

The facility to use for log messages generated by subsequent ulog() calls.

See LogFacility for recognized facility names.

identstring(optional)

A string identifying the program name. If omitted, the name of the calling process is used by default.

Returns: boolean
Example
// Log to dmesg and stderr
ulog_open(["stdio", "kmsg"], "daemon", "my-program");

// Use numeric constants and use implicit default ident
ulog_open(ULOG_SYSLOG, LOG_LOCAL0);

ulog_threshold(priorityopt) → {boolean}

Set ulog priority threshold.

This function configures the application wide log message threshold for log messages emitted with ulog(). Any message with a priority higher (= less severe) than the threshold priority will be discarded. This is useful to implement application wide verbosity settings without having to wrap ulog() invocations into a helper function or guarding code.

When no explicit threshold has been set, LOG_DEBUG is used by default, allowing log messages with all known priorities.

The ulog_threshold() function is OpenWrt specific and may not be present on other systems. There is no syslog equivalent to this ulog specific threshold mechanism.

The priority argument may be either a string value containing a priority name or one of the numeric LOG_* priority constants in the module namespace.

Returns true if a threshold was set.

Returns false if an invalid priority value was given.

Parameters:
NameTypeDescription
prioritynumber | LogPriority(optional)

The priority threshold to configure.

See LogPriority for recognized priority names.

Returns: boolean
Example
// Set threshold to "warning" or more severe
ulog_threshold(LOG_WARNING);

// This message will be supressed
ulog(LOG_DEBUG, "Testing thresholds");

// Using priority name
ulog_threshold("debug");

Type Definitions

LogFacility: string

The following log facility strings are recognized:

FacilityDescription
"auth"Authentication/authorization messages.
"authpriv"Private authentication messages.
"cron"Clock daemon (cron and at commands).
"daemon"System daemons without separate facility values.
"ftp"FTP server daemon.
"kern"Kernel messages.
"lpr"Line printer subsystem.
"mail"Mail system.
"news"Network news subsystem.
"syslog"Messages generated internally by syslogd.
"user"Generic user-level messages.
"uucp"UUCP subsystem.
"local0"Local use 0 (custom facility).
"local1"Local use 1 (custom facility).
"local2"Local use 2 (custom facility).
"local3"Local use 3 (custom facility).
"local4"Local use 4 (custom facility).
"local5"Local use 5 (custom facility).
"local6"Local use 6 (custom facility).
"local7"Local use 7 (custom facility).

LogOption: string

The following log option strings are recognized:

Log OptionDescription
"pid"Include PID with each message.
"cons"Log to console if an error occurs while sending to syslog.
"ndelay"Open the connection to the logger immediately.
"odelay"Delay open until the first message is logged.
"nowait"Do not wait for child processes created during logging.

LogPriority: string

The following log priority strings are recognized:

PriorityDescription
"emerg"System is unusable.
"alert"Action must be taken immediately.
"crit"Critical conditions.
"err"Error conditions.
"warning"Warning conditions.
"notice"Normal, but significant, condition.
"info"Informational message.
"debug"Debug-level message.

UlogChannel: string

The following ulog channel strings are recognized:

ChannelDescription
"kmsg"Log to /dev/kmsg, log messages appear in dmesg.
"syslog"Use standard syslog() mechanism.
"stdio"Use stderr for log output.