You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by as...@apache.org on 2019/11/14 06:30:21 UTC
[qpid-proton] 02/03: PROTON-2131: Improved documentation of logger
API
This is an automated email from the ASF dual-hosted git repository.
astitcher pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/qpid-proton.git
commit c692aa831d838aa1ee7efe3a819862b5522bd700
Author: Andrew Stitcher <as...@apache.org>
AuthorDate: Wed Nov 13 23:48:30 2019 -0500
PROTON-2131: Improved documentation of logger API
---
c/include/proton/logger.h | 145 ++++++++++++++++++++++++++++++++++++----------
1 file changed, 116 insertions(+), 29 deletions(-)
diff --git a/c/include/proton/logger.h b/c/include/proton/logger.h
index ae4d153..f19d175 100644
--- a/c/include/proton/logger.h
+++ b/c/include/proton/logger.h
@@ -19,9 +19,13 @@
* under the License.
*/
-/**@file
+/**
+ * @file
+ * @copybrief logger
+ * @copydetails logger
*
- * General proton logging facility
+ * @defgroup logger Logger
+ * @ingroup core
*/
#include <proton/import_export.h>
@@ -34,22 +38,67 @@
extern "C" {
#endif
+/**
+ * @addtogroup logger
+ * @{
+ *
+ * Facility for logging messages
+ *
+ * The proton library has internal logging which provides information about the
+ * functioning of the library. This Logger system (see @ref pn_logger_t) allows applications
+ * to customize how the logging is recorded and output.
+ *
+ * Each logged message has an attached level (see @ref pn_log_level_t) which
+ * indicates how important the message is; and also has an attached subsystem
+ * (see @ref pn_log_subsystem_t) which indicates which part of proton is producing#
+ * the log message. The levels go from "Critical" which indicates a condition the library cannot
+ * recover from.
+ *
+ * Applications receive log messages by registering a callback function (@ref pn_log_sink_t). This
+ * receives the logged message and other information and allows the application to consume the
+ * logged messages as it wants. Applications can filter the messages that they receive by setting
+ * bit masks in the logger. They can set the logger filtering both by subsystem and by level.
+ * Additionally, since the callback contains both the subsystem and level information for each
+ * logged message, applications can impose further, more complex, filters of their own.
+ *
+ * Each application will have a default logger which can be retrieved with @ref pn_default_logger.
+ * The default logger is used as the template for every other logger that is created. So an efficient
+ * way to configure logging is to configure the default logger at the very start of the application
+ * before any other loggers get created.
+ *
+ * Loggers are associated with different proton objects, primarily the transport object
+ * (@ref pn_transport_t) and each logger controls the logging for the associated object. This means
+ * that for example in order to control the logging for an AMQP connection you need to acquire the
+ * logger object from the transport object using @ref pn_transport_logger and to configure that.
+ *
+ * Initially the defaults are to log every subsystem but not any level (except 'Critical' which is
+ * always logged). This means in effect that it is only necessary to turn on the log levels that
+ * are interesting and all subsystems will log. Of course you can turn off subsystems that are not
+ * interesting or are too verbose.
+ *
+ * There is also a default log sink if the application does not register their own, but logging
+ * is turned on - this will output the log message to standard error.
+ */
+
+/**
+ * The logger object allows library logging to be controlled
+ */
typedef struct pn_logger_t pn_logger_t;
/**
- * Definitions for different subsystems that can log messages
+ * Definitions for different subsystems that can log messages.
* Note that these are exclusive bits so that you can specify multiple
* subsystems to filter
*/
typedef enum pn_log_subsystem_t {
- PN_SUBSYSTEM_NONE = 0,
- PN_SUBSYSTEM_IO = 1,
- PN_SUBSYSTEM_EVENT = 2,
- PN_SUBSYSTEM_AMQP = 4,
- PN_SUBSYSTEM_SSL = 8,
- PN_SUBSYSTEM_SASL = 16,
- PN_SUBSYSTEM_BINDING = 32,
- PN_SUBSYSTEM_ALL = 65535
+ PN_SUBSYSTEM_NONE = 0, /**< No subsystem */
+ PN_SUBSYSTEM_IO = 1, /**< Low level Input/Output */
+ PN_SUBSYSTEM_EVENT = 2, /**< Events */
+ PN_SUBSYSTEM_AMQP = 4, /**< AMQP protocol processing */
+ PN_SUBSYSTEM_SSL = 8, /**< TLS/SSL protocol processing */
+ PN_SUBSYSTEM_SASL = 16, /**< SASL protocol processing */
+ PN_SUBSYSTEM_BINDING = 32, /**< Language binding */
+ PN_SUBSYSTEM_ALL = 65535 /**< Every subsystem */
} pn_log_subsystem_t; /* We hint to the compiler it can use 16 bits for this value */
/**
@@ -58,16 +107,16 @@ typedef enum pn_log_subsystem_t {
* severities to filter
*/
typedef enum pn_log_level_t {
- PN_LEVEL_NONE = 0,
- PN_LEVEL_CRITICAL = 1, /* Something is wrong and can't be fixed - probably a library bug */
- PN_LEVEL_ERROR = 2, /* Something went wrong */
- PN_LEVEL_WARNING = 4, /* Something unusual happened but not necessarily an error */
- PN_LEVEL_INFO = 8, /* Something that might be interesting happened */
- PN_LEVEL_DEBUG = 16, /* Something you might want to know about happened */
- PN_LEVEL_TRACE = 32, /* Detail about something that happened */
- PN_LEVEL_FRAME = 64, /* Protocol frame traces */
- PN_LEVEL_RAW = 128, /* Raw protocol bytes */
- PN_LEVEL_ALL = 65535 /* Every possible severity */
+ PN_LEVEL_NONE = 0, /**< No level */
+ PN_LEVEL_CRITICAL = 1, /**< Something is wrong and can't be fixed - probably a library bug */
+ PN_LEVEL_ERROR = 2, /**< Something went wrong */
+ PN_LEVEL_WARNING = 4, /**< Something unusual happened but not necessarily an error */
+ PN_LEVEL_INFO = 8, /**< Something that might be interesting happened */
+ PN_LEVEL_DEBUG = 16, /**< Something you might want to know about happened */
+ PN_LEVEL_TRACE = 32, /**< Detail about something that happened */
+ PN_LEVEL_FRAME = 64, /**< Protocol frame traces */
+ PN_LEVEL_RAW = 128, /**< Raw protocol bytes */
+ PN_LEVEL_ALL = 65535 /**< Every possible level */
} pn_log_level_t; /* We hint to the compiler that it can use 16 bits for this value */
/**
@@ -75,52 +124,86 @@ typedef enum pn_log_level_t {
*/
typedef void (*pn_log_sink_t)(intptr_t sink_context, pn_log_subsystem_t subsystem, pn_log_level_t severity, const char *message);
-/*
+/**
* Return the default library logger
+ *
+ * @return The global default logger
*/
PN_EXTERN pn_logger_t *pn_default_logger(void);
/**
* Create a new logger
+ *
+ * Note that loggers must be deallocated with @ref pn_logger_free after use.
+ *
+ * @return a newly constructed logger
*/
PN_EXTERN pn_logger_t *pn_logger(void);
/**
* Free an existing logger
+ *
+ * @param[in] logger the logger to free
*/
PN_EXTERN void pn_logger_free(pn_logger_t *logger);
/**
* Get a human readable name for a logger severity
+ *
+ * @param[in] level the logging level
+ * @return readable name for that level
*/
-PN_EXTERN const char *pn_logger_level_name(pn_log_level_t severity);
+PN_EXTERN const char *pn_logger_level_name(pn_log_level_t level);
/**
* Get a human readable name for a logger subsystem
+ *
+ * @param[in] subsystem
+ * @return readable name for that subsystem
*/
PN_EXTERN const char *pn_logger_subsystem_name(pn_log_subsystem_t subsystem);
/**
* Set a logger's tracing flags.
*
- * Set trace flags to control what a logger logs.
+ * Set individual trace flags to control what a logger logs.
*
* The trace flags for a logger control what sort of information is
- * logged. See pn_log_severity_t and pn_log_subsystem_t for more details.
+ * logged. See @ref pn_log_level_t and @ref pn_log_subsystem_t for more details.
+ *
+ * Note that log messages with a level of @ref PN_LEVEL_CRITICAL will always be logged.
+ * Otherwise log message are only logged if the subsystem and level flags both match a
+ * flag in the masks held by the logger.
+ *
+ * If you don't want to affect the subsystem flags then you can set subsystem to
+ * PN_SUBSYSTEM_NONE. likewise level to PN_LEVEL_NONE if you don't want to
+ * affect the level flags.
*
* @param[in] logger the logger
+ * @param[in] subsystem bits representing subsystems to turn on trace for
+ * @param[in] level bits representing log levels to turn on trace for
*/
-PN_EXTERN void pn_logger_set_mask(pn_logger_t *logger, pn_log_subsystem_t subsystem, pn_log_level_t severity);
+PN_EXTERN void pn_logger_set_mask(pn_logger_t *logger, pn_log_subsystem_t subsystem, pn_log_level_t level);
/**
* Clear a logger's tracing flags.
*
- * Clear trace flags to control what a logger logs.
+ * Clear individual trace flags to control what a logger logs.
*
* The trace flags for a logger control what sort of information is
- * logged. See pn_log_severity_t and pn_log_subsystem_t for more details.
+ * logged. See @ref pn_log_level_t and @ref pn_log_subsystem_t for more details.
+ *
+ * Note that log messages with a level of @ref PN_LEVEL_CRITICAL will always be logged.
+ * Otherwise log message are only logged if the subsystem and level flags both match a
+ * flag in the masks held by the logger.
+ *
+ * If you don't want to affect the subsystem flags then you can set subsystem to
+ * PN_SUBSYSTEM_NONE. likewise level to PN_LEVEL_NONE if you don't want to
+ * affect the level flags.
*
* @param[in] logger the logger
+ * @param[in] subsystem bits representing subsystems to turn off trace for
+ * @param[in] level bits representing log levels to turn off trace for
*/
PN_EXTERN void pn_logger_reset_mask(pn_logger_t *logger, pn_log_subsystem_t subsystem, pn_log_level_t severity);
@@ -154,7 +237,7 @@ PN_EXTERN pn_log_sink_t pn_logger_get_log_sink(pn_logger_t *logger);
PN_EXTERN intptr_t pn_logger_get_log_sink_context(pn_logger_t *logger);
/**
- * * Log a printf formatted using the logger
+ * Log a printf formatted message using the logger
*
* This is mainly for use in proton internals , but will allow application log messages to
* be processed the same way.
@@ -168,4 +251,8 @@ PN_EXTERN void pn_logger_logf(pn_logger_t *logger, pn_log_subsystem_t subsystem,
}
#endif
+/**
+ * @}
+ */
+
#endif
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org