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 Name	Description
`LOG_PID`	Include PID with each message.
`LOG_CONS`	Log to console if error occurs while sending to syslog.
`LOG_NDELAY`	Open the connection to the logger immediately.
`LOG_ODELAY`	Delay open until the first message is logged.
`LOG_NOWAIT`	Do not wait for child processes created during logging.

Syslog Facilities

Constant Name	Description
`LOG_AUTH`	Authentication/authorization messages.
`LOG_AUTHPRIV`	Private authentication messages.
`LOG_CRON`	Clock daemon (cron and at commands).
`LOG_DAEMON`	System daemons without separate facility values.
`LOG_FTP`	FTP server daemon.
`LOG_KERN`	Kernel messages.
`LOG_LPR`	Line printer subsystem.
`LOG_MAIL`	Mail system.
`LOG_NEWS`	Network news subsystem.
`LOG_SYSLOG`	Messages generated internally by syslogd.
`LOG_USER`	Generic user-level messages.
`LOG_UUCP`	UUCP subsystem.
`LOG_LOCAL0`	Local use 0 (custom facility).
`LOG_LOCAL1`	Local use 1 (custom facility).
`LOG_LOCAL2`	Local use 2 (custom facility).
`LOG_LOCAL3`	Local use 3 (custom facility).
`LOG_LOCAL4`	Local use 4 (custom facility).
`LOG_LOCAL5`	Local use 5 (custom facility).
`LOG_LOCAL6`	Local use 6 (custom facility).
`LOG_LOCAL7`	Local use 7 (custom facility).

Syslog Priorities

Constant Name	Description
`LOG_EMERG`	System is unusable.
`LOG_ALERT`	Action must be taken immediately.
`LOG_CRIT`	Critical conditions.
`LOG_ERR`	Error conditions.
`LOG_WARNING`	Warning conditions.
`LOG_NOTICE`	Normal, but significant, condition.
`LOG_INFO`	Informational message.
`LOG_DEBUG`	Debug-level message.

Ulog channels

Constant Name	Description
`ULOG_KMSG`	Log messages to `/dev/kmsg` (dmesg).
`ULOG_STDIO`	Log messages to stdout.
`ULOG_SYSLOG`	Log messages to syslog.

Source: lib/log.c, line 17

Methods

ERR(format, …argsopt) → {boolean}

Invoke ulog with LOG_ERR.

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

See ulog() for details.

Parameters:

Name	Type	Description
`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!");

Source: lib/log.c, line 974

INFO(format, …argsopt) → {boolean}

Invoke ulog with LOG_INFO.

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

See ulog() for details.

Parameters:

Name	Type	Description
`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");

Source: lib/log.c, line 887

NOTE(format, …argsopt) → {boolean}

Invoke ulog with LOG_NOTICE.

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

See ulog() for details.

Parameters:

Name	Type	Description
`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");

Source: lib/log.c, line 916

WARN(format, …argsopt) → {boolean}

Invoke ulog with LOG_WARNING.

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

See ulog() for details.

Parameters:

Name	Type	Description
`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");

Source: lib/log.c, line 945

closelog()

Close connection to system logger.

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

Source: lib/log.c, line 534

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:

Name Type Description

Name	Type	Description
`ident`	string	(optional) A string identifying the program name. If omitted, the name of the calling process is used by default.
`options`	number \| LogOption \| LogOption[]	(optional) Logging options to use. See LogOption for recognized option names.
`facility`	number \| LogFacility	(optional, default: `"user"`) The facility to use for log messages generated by subsequent syslog calls. See LogFacility for recognized facility names.

ident

string

(optional)

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

options

number | LogOption | LogOption[]

(optional)

Logging options to use.

See LogOption for recognized option names.

facility

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

Source: lib/log.c, line 369

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:

Name Type Description

Name	Type	Description
`priority`	number \| 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.

priority

number | 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] });

Source: lib/log.c, line 431

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:

Name Type Description

Name	Type	Description
`priority`	number \| 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.

priority

number | 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] });

Source: lib/log.c, line 733
See: module:log#ulog_open
module:log#ulog_threshold
module:log#syslog

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.

Source: lib/log.c, line 804
See: module:log#closelog

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:

Name Type Description

Name	Type	Description
`channel`	number \| UlogChannel \| UlogChannel[]	(optional) Specifies the log channels to use. See UlogChannel for recognized channel names.
`facility`	number \| LogFacility	(optional) The facility to use for log messages generated by subsequent `ulog()` calls. See LogFacility for recognized facility names.
`ident`	string	(optional) A string identifying the program name. If omitted, the name of the calling process is used by default.

channel

number | UlogChannel | UlogChannel[]

(optional)

Specifies the log channels to use.

See UlogChannel for recognized channel names.

facility

number | LogFacility

(optional)

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

See LogFacility for recognized facility names.

ident

string

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

Source: lib/log.c, line 619

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:

Name Type Description

Name	Type	Description
`priority`	number \| LogPriority	(optional) The priority threshold to configure. See LogPriority for recognized priority names.

priority

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

Source: lib/log.c, line 832

Type Definitions

LogFacility: string

The following log facility strings are recognized:

Facility	Description
`"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).

Source: lib/log.c, line 157

LogOption: string

The following log option strings are recognized:

Log Option	Description
`"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.

Source: lib/log.c, line 134

LogPriority: string

The following log priority strings are recognized:

Priority	Description
`"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.

Source: lib/log.c, line 213

UlogChannel: string

The following ulog channel strings are recognized:

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

Source: lib/log.c, line 552