diff options
Diffstat (limited to 'docs/ref')
| -rw-r--r-- | docs/ref/SUMMARY.md | 7 | ||||
| -rw-r--r-- | docs/ref/api/log/nng_log.md | 75 | ||||
| -rw-r--r-- | docs/ref/api/log/nng_log_facility.md | 47 | ||||
| -rw-r--r-- | docs/ref/api/log/nng_log_level.md | 43 | ||||
| -rw-r--r-- | docs/ref/api/log/nng_log_logger.md | 47 |
5 files changed, 219 insertions, 0 deletions
diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index c5ad5f9a..094eac11 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -19,6 +19,13 @@ - [nng_mtx](./api/thr/nng_mtx.md) - [nng_thread](./api/thr/nng_thread.md) + - [Logging](./api/log/index.md) + + - [nng_log](./api/log/nng_log.md) + - [nng_log_facility](./api/log/nng_log_facility.md) + - [nng_log_level](./api/log/nng_log_level.md) + - [nng_log_logger](./api/log/nng_log_logger.md) + - [Utility Functions](./api/util/index.md) - [nng_alloc](./api/util/nng_alloc.md) diff --git a/docs/ref/api/log/nng_log.md b/docs/ref/api/log/nng_log.md new file mode 100644 index 00000000..5d0db5a9 --- /dev/null +++ b/docs/ref/api/log/nng_log.md @@ -0,0 +1,75 @@ +# nng_log + +## NAME + +# nng_log --- log messages + +## SYNOPSIS + +```c +#include <nng/nng.h> + +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, ...); + +void nng_log_auth(nng_log_level level, const char *msgid, const char *msg, ...); +``` + +## DESCRIPTION + +The {{i:`nng_log`}} functions are used to post a message to system or application {{i:logs}}. + +The first five forms all post a message at the severity indicated by the function name. +The _msgid_ should be a short message identifier that should indicate the message in question. +A `NULL` value for _msgid_ can be used as well. + +Message identifiers can be used to assist in filtering and classifying logged messages. +These should uniquely identify the nature of the problem, whe possible, to assist in trouble-shooting. +They should also be short. +Eight characters or less is ideal, and more than sixteen is strongly discouraged. +Message identifiers may not be displayed to human readers, or may not be displayed by default. +Therefore, any information in the message identifier should also be in the log content. + +The message is formatted as if by `sprintf`, using `msg` as the format, and remaining arguments as arguments to the format. + +The final function, {{i:`nng_log_auth`}}, is used for posting authentication related messages which might be treated specially, +such as be storing them in a separate (and presumably more secure) log file. +It takes the severity as a level in _level_. +The severity can be one of the following values: + +- `NNG_LOG_ERR` +- `NNG_LOG_WARN` +- `NNG_LOG_NOTICE` +- `NNG_LOG_INFO` +- `NNG_LOG_DEBUG` + +The message itself is handled according to the logging facility set up with [`nng_log_set_logger`][log_logger]. +Message delivery is best effort, and messages may be suppressed based on the priority set with [`nng_log_set_level`][log_level]. + +Note that in order to get log messages, a suitable logger must be set using {{i:`nng_log_set_logger`}}. +The default logger, {{i:`nng_null_logger`}} simply discards logged content. + +> [!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. + +## SEE ALSO + +[nng_log_facility][log_facility], +[nng_log_level][log_level], +[nng_log_logger][log_logger] + +[log_facility]: ./nng_log_facility.md +[log_level]: ./nng_log_level.md +[log_logger]: ./nng_log_logger.md diff --git a/docs/ref/api/log/nng_log_facility.md b/docs/ref/api/log/nng_log_facility.md new file mode 100644 index 00000000..28ffd05f --- /dev/null +++ b/docs/ref/api/log/nng_log_facility.md @@ -0,0 +1,47 @@ +# nng_log_facility + +## NAME + +nng_log_facility --- facility or category for log messages + +## SYNOPSIS + +```c +#include <nng/nng.h> + +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; + +void nng_log_set_facility(nng_log_facility facility); +``` + +## DESCRIPTION + +An {{i:`nng_log_facility`}} object represents a facility, which can be thought of as +a category, for log message. Normally these are used to identify the source of the +message. The facility values here correspond to those typical used with the UNIX +`syslog` logging system. + +The `nng_log_set_facility` is used to set the _facility_ of the application posting logs, +so that messages that are submitted by the application can be correctly attributed to +the application itself. It may also help in message routing. + +Note that while the log levels used here overlap with common levels used by the +`syslog` system found on POSIX systems, applications should not the numeric values +being the same. + +## SEE ALSO + +[nng_log](./nng_log.md), +[nng_log_level](./nng_log_level.md) diff --git a/docs/ref/api/log/nng_log_level.md b/docs/ref/api/log/nng_log_level.md new file mode 100644 index 00000000..a875a7e0 --- /dev/null +++ b/docs/ref/api/log/nng_log_level.md @@ -0,0 +1,43 @@ +# nng_log_level + +## NAME + +nng_log_level --- severity level for logging messages + +## SYNOPSIS + +```c +#include <nng/nng.h> + +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; + +void nng_log_set_level(nng_log_level level); +nng_log_level nng_log_get_level(void); +``` + +## DESCRIPTION + +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 is used to set the minimum severity to _level_ for processing log messages. +Any messages with a less severe rating are not processed and simply are discarded. +Use `NNG_LOG_NONE` to suppress all log messages. +Use `NNG_LOG_DEBUG` to receive all log messages. + +The `nng_log_get_level` function returns the current log level, which can be useful +to elide processing to create log content that will simply be discarded anyway. + +## SEE ALSO + +[nng_log](./nng_log.md), +[nng_log_facility](./nng_log_facility.md), +[nng_log_logger](./nng_log_logger.md) diff --git a/docs/ref/api/log/nng_log_logger.md b/docs/ref/api/log/nng_log_logger.md new file mode 100644 index 00000000..26551091 --- /dev/null +++ b/docs/ref/api/log/nng_log_logger.md @@ -0,0 +1,47 @@ +# nng_log_logger + +## NAME + +nng_log_logger --- logging handler + +## SYNOPSIS + +```c +#include <nng/nng.h> + +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); +``` + +## DESCRIPTION + +An {{i:`nng_logger`}}{{hi:logger}} is a function used as a handler to process logged messages. +This is responsible for the final disposition of the logged messages. + +The {{i:`nng_log_set_logger`}} function is used to set the base logging function to _logger_. +The _logger_ may be a user defined function to process log messages. +Only a single logger may be registered at a time. +If needed, the logger should make copies of either _msgid_ or _msg_, as they will not be valid after the logger returns. + +The {{i:`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 {{i:`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 supressed by setting either the `NO_COLOR` or `NNG_LOG_NO_COLOR` environment variables. + +The {{i:`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`. + +## SEE ALSO + +[nng_log](./nng_log.md), +[nng_log_facility](./nng_log_facility.md), +[nng_log_level](./nng_log_level.md) |