| #ifndef LOGGER_H |
| #define LOGGER_H |
| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| */ |
| |
| /** |
| * @file |
| * @copybrief logger |
| * @copydetails logger |
| * |
| * @defgroup logger Logger |
| * @ingroup core |
| */ |
| |
| #include <proton/import_export.h> |
| #include <proton/object.h> |
| |
| #include <stdarg.h> |
| #include <stdint.h> |
| |
| #ifdef __cplusplus |
| 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. |
| * 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, /**< No subsystem */ |
| PN_SUBSYSTEM_MEMORY = 1, /**< Memory usage */ |
| PN_SUBSYSTEM_IO = 2, /**< Low level Input/Output */ |
| PN_SUBSYSTEM_EVENT = 4, /**< Events */ |
| PN_SUBSYSTEM_AMQP = 8, /**< AMQP protocol processing */ |
| PN_SUBSYSTEM_SSL = 16, /**< TLS/SSL protocol processing */ |
| PN_SUBSYSTEM_SASL = 32, /**< SASL protocol processing */ |
| PN_SUBSYSTEM_BINDING = 64, /**< 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 */ |
| |
| /** |
| * Definitions for different severities of log messages |
| * Note that these are exclusive bits so that you can specify multiple |
| * severities to filter |
| */ |
| typedef enum pn_log_level_t { |
| 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 */ |
| |
| /** |
| * Callback for sinking logger messages. |
| */ |
| 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); |
| |
| /** |
| * 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 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 individual trace flags to control what a logger logs. |
| * |
| * The trace flags for a logger control what sort of information is |
| * 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, uint16_t subsystem, uint16_t level); |
| |
| /** |
| * Clear a logger's tracing flags. |
| * |
| * Clear individual trace flags to control what a logger logs. |
| * |
| * The trace flags for a logger control what sort of information is |
| * 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, uint16_t subsystem, uint16_t level); |
| |
| /** |
| * Set the tracing function used by a logger. |
| * |
| * The tracing function is called to perform logging. Overriding this |
| * function allows embedding applications to divert the engine's |
| * logging to a place of their choice. |
| * |
| * @param[in] logger the logger |
| * @param[in] sink the tracing function |
| * @param[in] sink_context user specified context to pass into each call of the tracing callback |
| */ |
| PN_EXTERN void pn_logger_set_log_sink(pn_logger_t *logger, pn_log_sink_t sink, intptr_t sink_context); |
| |
| /** |
| * Get the tracing function used by a logger. |
| * |
| * @param[in] logger the logger |
| * @return the tracing sink function used by a logger |
| */ |
| PN_EXTERN pn_log_sink_t pn_logger_get_log_sink(pn_logger_t *logger); |
| |
| /** |
| * Get the sink context used by a logger. |
| * |
| * @param[in] logger the logger |
| * @return the sink context used by a logger |
| */ |
| PN_EXTERN intptr_t pn_logger_get_log_sink_context(pn_logger_t *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. |
| * |
| * @param[in] logger the logger |
| * @param[in] subsystem the subsystem which is producing this log message |
| * @param[in] level the log level of the log message |
| * @param[in] fmt the printf formatted message to be logged |
| */ |
| PN_EXTERN void pn_logger_logf(pn_logger_t *logger, pn_log_subsystem_t subsystem, pn_log_level_t level, const char *fmt, ...); |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| /** |
| * @} |
| */ |
| |
| #endif |