+ +

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.

NNG Reference Manual (DRAFT)