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.

5 files changed, 99 insertions, 2 deletions

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. <info@staysail.tech>
+# Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
 # Copyright 2018 Capitar IT Group BV <info@capitar.com>
 # Copyright 2019 Devolutions <info@devolutions.net>
 #
@@ -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. <info@staysail.tech>
+//
+// 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 <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;
+
+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.adoc b/docs/man/nng_log_set_level.3.adoc
index 012f93f8..5501e9ce 100644
--- a/docs/man/nng_log_set_level.adoc
+++ b/docs/man/nng_log_set_level.3.adoc
@@ -39,4 +39,5 @@ 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_logger.adoc b/docs/man/nng_log_set_logger.3.adoc
index eedbca49..eedbca49 100644
--- a/docs/man/nng_log_set_logger.adoc
+++ b/docs/man/nng_log_set_logger.3.adoc
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. <info@staysail.tech>
+//
+// 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 <nng/nng.h>
+
+#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)]