From 56507ab5c4db009be5251bde832f594fe5ed3d5e Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 21 Apr 2024 12:23:07 -0700 Subject: Logging improvements (#1816) * Add nng_str_sockaddr to get string representation of socket address. * Added nng_log_get_level() is meant to allow users to obtain the current level and avoid some possibly expensive operations just to collect debugging information when debugging is not in effect. We use a custom logger for NUTS, and this fits within the NUTS test framework well, so that if -v is supplied we get more content. All tests now get this by default. --- docs/man/CMakeLists.txt | 6 +++-- docs/man/nng_log_get_level.3.adoc | 42 ++++++++++++++++++++++++++++++ docs/man/nng_log_set_level.3.adoc | 43 +++++++++++++++++++++++++++++++ docs/man/nng_log_set_level.adoc | 42 ------------------------------ docs/man/nng_log_set_logger.3.adoc | 53 ++++++++++++++++++++++++++++++++++++++ docs/man/nng_log_set_logger.adoc | 53 -------------------------------------- docs/man/nng_str_sockaddr.3.adoc | 52 +++++++++++++++++++++++++++++++++++++ 7 files changed, 194 insertions(+), 97 deletions(-) create mode 100644 docs/man/nng_log_get_level.3.adoc create mode 100644 docs/man/nng_log_set_level.3.adoc delete mode 100644 docs/man/nng_log_set_level.adoc create mode 100644 docs/man/nng_log_set_logger.3.adoc delete mode 100644 docs/man/nng_log_set_logger.adoc create mode 100644 docs/man/nng_str_sockaddr.3.adoc (limited to 'docs') diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt index ba3508d2..e839b0d6 100644 --- a/docs/man/CMakeLists.txt +++ b/docs/man/CMakeLists.txt @@ -1,5 +1,5 @@ # -# Copyright 2020 Staysail Systems, Inc. +# Copyright 2024 Staysail Systems, Inc. # Copyright 2018 Capitar IT Group BV # Copyright 2019 Devolutions # @@ -116,8 +116,9 @@ if (NNG_ENABLE_DOC) nng_listener_setopt nng_listener_start nng_log + nng_log_get_level nng_log_set_facility - nng_log_set_loevel + nng_log_set_level nng_log_set_logger nng_msg_alloc nng_msg_append @@ -181,6 +182,7 @@ if (NNG_ENABLE_DOC) nng_stat_type nng_stat_unit nng_stat_value + nng_str_sockaddr nng_strdup nng_strerror nng_strfree diff --git a/docs/man/nng_log_get_level.3.adoc b/docs/man/nng_log_get_level.3.adoc new file mode 100644 index 00000000..7ff90906 --- /dev/null +++ b/docs/man/nng_log_get_level.3.adoc @@ -0,0 +1,42 @@ += nng_log_get_level(3) +// +// Copyright 2024 Staysail Systems, Inc. +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_log_get_level - get minimum level for logging messagse + +== SYNOPSIS + +[source, c] +---- +#include + +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; + +nng_log_level nng_log_set_level(void); +---- + +== DESCRIPTION + +The `nng_log_get_level` function is used to get the minimum severity to _level_ for processing log messages. +The intended use case is to avoid expensive operations used solely to provide debugging information in logs, +if the logged content would merely be discarded. + +== SEE ALSO + +xref:nng_log_set_facility.3.adoc[nng_log_set_facility(3)], +xref:nng_log_set_level.3.adoc[nng_log_set_level(3)] diff --git a/docs/man/nng_log_set_level.3.adoc b/docs/man/nng_log_set_level.3.adoc new file mode 100644 index 00000000..5501e9ce --- /dev/null +++ b/docs/man/nng_log_set_level.3.adoc @@ -0,0 +1,43 @@ += nng_log_set_level(3) +// +// Copyright 2024 Staysail Systems, Inc. +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_log_set_level - set minimum level for logging messagse + +== SYNOPSIS + +[source, c] +---- +#include + +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); +---- + +== DESCRIPTION + +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. + +== SEE ALSO + +xref:nng_log_get_level.3.adoc[nng_log_set_level(3)] +xref:nng_log_set_facility.3.adoc[nng_log_set_facility(3)] diff --git a/docs/man/nng_log_set_level.adoc b/docs/man/nng_log_set_level.adoc deleted file mode 100644 index 012f93f8..00000000 --- a/docs/man/nng_log_set_level.adoc +++ /dev/null @@ -1,42 +0,0 @@ -= nng_log_set_level(3) -// -// Copyright 2024 Staysail Systems, Inc. -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_log_set_level - set minimum level for logging messagse - -== SYNOPSIS - -[source, c] ----- -#include - -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); ----- - -== DESCRIPTION - -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. - -== SEE ALSO - -xref:nng_log_set_facility.3.adoc[nng_log_set_facility(3)] diff --git a/docs/man/nng_log_set_logger.3.adoc b/docs/man/nng_log_set_logger.3.adoc new file mode 100644 index 00000000..eedbca49 --- /dev/null +++ b/docs/man/nng_log_set_logger.3.adoc @@ -0,0 +1,53 @@ += nng_log_set_logger(3) +// +// Copyright 2024 Staysail Systems, Inc. +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_log_set_logger - set logging handler + +== SYNOPSIS + +[source, c] +---- +#include + +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 + +The `nng_log_set_logger` 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 those may not be valid once the logger function returns. + +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 supressed 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 the `nng_stderr_log` may be used as a fallback. + +== SEE ALSO + +xref:nng_log_set_facility.3.adoc[nng_log_set_facility(3)], +xref:nng_log_set_level.3.adoc[nng_log_set_level(3)], +xref:nng_log.3.adoc[nng_log(3)] diff --git a/docs/man/nng_log_set_logger.adoc b/docs/man/nng_log_set_logger.adoc deleted file mode 100644 index eedbca49..00000000 --- a/docs/man/nng_log_set_logger.adoc +++ /dev/null @@ -1,53 +0,0 @@ -= nng_log_set_logger(3) -// -// Copyright 2024 Staysail Systems, Inc. -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_log_set_logger - set logging handler - -== SYNOPSIS - -[source, c] ----- -#include - -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 - -The `nng_log_set_logger` 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 those may not be valid once the logger function returns. - -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 supressed 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 the `nng_stderr_log` may be used as a fallback. - -== SEE ALSO - -xref:nng_log_set_facility.3.adoc[nng_log_set_facility(3)], -xref:nng_log_set_level.3.adoc[nng_log_set_level(3)], -xref:nng_log.3.adoc[nng_log(3)] diff --git a/docs/man/nng_str_sockaddr.3.adoc b/docs/man/nng_str_sockaddr.3.adoc new file mode 100644 index 00000000..03999d1a --- /dev/null +++ b/docs/man/nng_str_sockaddr.3.adoc @@ -0,0 +1,52 @@ += nng_str_sockaddr(3) +// +// Copyright 2024 Staysail Systems, Inc. +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + + +nng_str_sockaddr - get string representation of socket address + +== SYNOPSIS + +[source, c] +---- +#include + +#define NNG_MAXADDRSTRLEN (NNG_MAXADDRLEN+16) +const char *nng_str_sockaddr(const nng_sockaddr *sa, char *buf, size_t bufsz) +---- + +== DESCRIPTION + +The `nng_str_sockaddr()` is used to provide a displayable representation +for the socket address _sa_. +The content will be stored the location provided by _buf_, and will be +formatted to fit within _bufsz_ bytes, truncating if necessary. + +As long as _bufsz_ is greater than zero, the result will be properly +zero-terminated in the usual fashion. + +The `NNG_MAXADDRSTRLEN` can be used to provide a buffer large enough to hold most socket addresses. +It is possible for applications to use very much larger socket addresses (using very long paths +for IPC or inproc), but such addresses are not generally compatible with other implementations, +and will be truncated here. + +== RETURN VALUES + +This function returns the _buf_ argument. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng_sockaddr.5.adoc[nng_sockaddr(5)] -- cgit v1.2.3-70-g09d2