Logging

This chapter describes the support for message logs. Both applications and NNG itself can emit logs, which can be useful for application field support and debugging. Additionally applications can customize the handling of this logging as needed.

Note that logging is disabled by default unless an application configures a suitable logger with nng_log_set_logger.

Submitting Logs

void nng_log_err(const char *msgid, const char *msg, ...);
void nng_log_warn(const char *msgid, const char *msg, ...);
void nng_log_notice(const char *msgid, const char *msg, ...);
void nng_log_info(const char *msgid, const char *msg, ...);
void nng_log_debug(const char *msgid, const char *msg, ...);

These functions inject a a message into the logging system, where it will be processed and potentially go to system logs, standard output, or procssed further.

The msgid is a short prefix that should uniquely identify the message, possibly also with some kind of category. It is recommended that strings between 8 and 16 charactes be used. As this may, but will not necessarily be displayed to the user, the content of the message should not appear solely in this field. A NULL value is permitted here, but that may make filtering the message or other automatic processing more difficult.

The msg is a printf-style format string, which is used to format the message content. The following arguments are consumed in the same manner as printf.

tip

Applications should take care to limit the use of higher severity levels, as message logs are potentially expensive, increase stress for end users and administrators, and further may mask real problems if incorrectly over used.

Warnings and error messages should be concise and actionable, and notices should only really be those things that are worthy of attention.

Informational and debug messages used during development should be removed when no longer needed, as these messages can overwhelm logging subsystems and can reduce the signal-to-noise value for the message logs, impairing the diagnostic value of the logs.

Auth Logs

void nng_log_auth(nng_log_level level, const char *msgid, const char *msg, ...);

The nng_log_auth function formats and injects a security related log message. (“Auth” can indicate either “authentication” or “authorization”.) The level is a log level. The msgid, msg, and any remaining arguments are processed in a fashion similar to the other logging functions, except that the logs may be are logged using the NNG_LOG_AUTH facility, and thus may be redirected or receive other special treatment.

Log Levels

typedef enum nng_log_level nng_log_level;

void nng_log_set_level(nng_log_level level);
nng_log_level nng_log_get_level(void);

The nng_log_level type represents a severity for logged messages. These levels correspond to those found in the UNIX syslog subsystem, although applications should not depend upon the values being identical.

The nng_log_set_level function sets the log level. Messages with a severity that is numerically greater than this (less-severe) will be discarded.

The nng_log_get_level function returns the log level most recently set by nng_log_set_level or the default if that function has not been called.

The log levels are defined as follows:

typedef enum nng_log_level {
    NNG_LOG_NONE   = 0, // used for filters only, NNG suppresses these
    NNG_LOG_ERR    = 3,
    NNG_LOG_WARN   = 4,
    NNG_LOG_NOTICE = 5,
    NNG_LOG_INFO   = 6,
    NNG_LOG_DEBUG  = 7
} nng_log_level;

The value NNG_LOG_NONE may be useful to suppress message logs altogether.

The default level is typically NNG_LOG_NOTICE, but applications should select a value rather than relying upon the default.

Log Facilities

typedef enum nng_log_facility

void nng_log_set_facility(nng_log_facility facility);

Logging facilities are used to indicate the source of a log message, and may be useful in routing and processing these logs. Traditionally these are used with the UNIX syslog system, and the values here represent some (but not all) of the values found there.

The following values are defined:

typedef enum nng_log_facility {
    NNG_LOG_USER   = 1,
    NNG_LOG_DAEMON = 3,
    NNG_LOG_AUTH   = 10,
    NNG_LOG_LOCAL0 = 16,
    NNG_LOG_LOCAL1 = 17,
    NNG_LOG_LOCAL2 = 18,
    NNG_LOG_LOCAL3 = 19,
    NNG_LOG_LOCAL4 = 20,
    NNG_LOG_LOCAL5 = 21,
    NNG_LOG_LOCAL6 = 22,
    NNG_LOG_LOCAL7 = 23,
} nng_log_facility;

The nng_log_set_facility function can be used to set the facility that the application will use when emitting log messages. This should be called as part of initialization of the application, if logging is to be used.

The default facility is typically NNG_LOG_USER, but applications should select a value rather than relying upon the default.

Log Handlers

typedef void (*nng_logger)(nng_log_level level, nng_log_facility facility,
    const char *msgid, const char *msg);

void nng_null_logger(nng_log_level, nng_log_facility, const char *, const char *);
void nng_stderr_logger(nng_log_level, nng_log_facility, const char *, const char *);
void nng_system_logger(nng_log_level, nng_log_facility, const char *, const char *);

void nng_log_set_logger(nng_logger logger);

Log handlers are responsible for actually processing the logged messages.

The nng_log_set_logger function installs the named logger, of type nng_logger, as the log handler. The function logger will be called when any message is meant to be processed. (Messages are first filtered by severity, then formatted, before calling the logger.)

Any previously installed logger is replaced by logger.

The nng_null_logger function is an implementation of nng_logger that simply discards the content. This is the default logger, so logging is disabled by default.

The nng_stderr_logger function is an implementation that logs messages to the standard error stream. It will attempt to colorize messages by the severity, if the standard error is a terminal device. This can be suppressed by setting either the NO_COLOR or NNG_LOG_NO_COLOR environment variables.

The nng_system_logger attempts to use an appropriate system facility to log messages. For POSIX systems, this means using syslog to process the messages. For other systems the defauilt behavior may be the same as nng_stderr_logger.