Logger

Facility for logging messages. More...

Typedefs
typedef struct pn_logger_t	pn_logger_t
	The logger object allows library logging to be controlled.
typedef void(*	pn_log_sink_t) (intptr_t sink_context, pn_log_subsystem_t subsystem, pn_log_level_t severity, const char *message)
	Callback for sinking logger messages.

Enumerations
enum	pn_log_subsystem_t {   PN_SUBSYSTEM_NONE , PN_SUBSYSTEM_MEMORY , PN_SUBSYSTEM_IO , PN_SUBSYSTEM_EVENT ,   PN_SUBSYSTEM_AMQP , PN_SUBSYSTEM_SSL , PN_SUBSYSTEM_SASL , PN_SUBSYSTEM_BINDING ,   PN_SUBSYSTEM_ALL }
	Definitions for different subsystems that can log messages. More...
enum	pn_log_level_t {   PN_LEVEL_NONE , PN_LEVEL_CRITICAL , PN_LEVEL_ERROR , PN_LEVEL_WARNING ,   PN_LEVEL_INFO , PN_LEVEL_DEBUG , PN_LEVEL_TRACE , PN_LEVEL_FRAME ,   PN_LEVEL_RAW , PN_LEVEL_ALL }
	Definitions for different severities of log messages Note that these are exclusive bits so that you can specify multiple severities to filter. More...

Functions
pn_logger_t *	pn_default_logger (void)
	Return the default library logger.
const char *	pn_logger_level_name (pn_log_level_t level)
	Get a human readable name for a logger severity.
const char *	pn_logger_subsystem_name (pn_log_subsystem_t subsystem)
	Get a human readable name for a logger subsystem.
void	pn_logger_set_mask (pn_logger_t *logger, uint16_t subsystem, uint16_t level)
	Set a logger's tracing flags.
void	pn_logger_reset_mask (pn_logger_t *logger, uint16_t subsystem, uint16_t level)
	Clear a logger's tracing flags.
void	pn_logger_set_log_sink (pn_logger_t *logger, pn_log_sink_t sink, intptr_t sink_context)
	Set the tracing function used by a logger.
pn_log_sink_t	pn_logger_get_log_sink (pn_logger_t *logger)
	Get the tracing function used by a logger.
intptr_t	pn_logger_get_log_sink_context (pn_logger_t *logger)
	Get the sink context used by a logger.
void	pn_logger_logf (pn_logger_t *logger, pn_log_subsystem_t subsystem, pn_log_level_t level, PN_PRINTF_FORMAT const char *fmt,...) PN_PRINTF_FORMAT_ATTR(4
	Log a printf formatted message using the logger.

Detailed Description

Facility for logging messages.

The proton library has internal logging which provides information about the functioning of the library. This Logger system (see pn_logger_t) allows applications to customize how the logging is recorded and output.

Each logged message has an attached level (see pn_log_level_t) which indicates how important the message is; and also has an attached subsystem (see 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 (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 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 (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 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.

Enumeration Type Documentation

pn_log_subsystem_t

enum pn_log_subsystem_t

Definitions for different subsystems that can log messages.

Note that these are exclusive bits so that you can specify multiple subsystems to filter

Enumerator
PN_SUBSYSTEM_NONE	No subsystem.
PN_SUBSYSTEM_MEMORY	Memory usage.
PN_SUBSYSTEM_IO	Low level Input/Output.
PN_SUBSYSTEM_EVENT	Events.
PN_SUBSYSTEM_AMQP	AMQP protocol processing.
PN_SUBSYSTEM_SSL	TLS/SSL protocol processing.
PN_SUBSYSTEM_SASL	SASL protocol processing.
PN_SUBSYSTEM_BINDING	Language binding.
PN_SUBSYSTEM_ALL	Every subsystem.

pn_log_level_t

enum pn_log_level_t

Definitions for different severities of log messages Note that these are exclusive bits so that you can specify multiple severities to filter.

Enumerator
PN_LEVEL_NONE	No level.
PN_LEVEL_CRITICAL	Something is wrong and can't be fixed - probably a library bug.
PN_LEVEL_ERROR	Something went wrong.
PN_LEVEL_WARNING	Something unusual happened but not necessarily an error.
PN_LEVEL_INFO	Something that might be interesting happened.
PN_LEVEL_DEBUG	Something you might want to know about happened.
PN_LEVEL_TRACE	Detail about something that happened.
PN_LEVEL_FRAME	Protocol frame traces.
PN_LEVEL_RAW	Raw protocol bytes.
PN_LEVEL_ALL	Every possible level.

Function Documentation

pn_default_logger()

pn_logger_t * pn_default_logger

(

void

)

Return the default library logger.

Returns

The global default logger

pn_logger_level_name()

const char * pn_logger_level_name

(

pn_log_level_t

level

)

Get a human readable name for a logger severity.

Parameters

[in]

level

the logging level

Returns

readable name for that level

pn_logger_subsystem_name()

const char * pn_logger_subsystem_name

(

pn_log_subsystem_t

subsystem

)

Get a human readable name for a logger subsystem.

Parameters

[in]

subsystem

Returns

readable name for that subsystem

pn_logger_set_mask()

void pn_logger_set_mask	(	pn_logger_t *	logger,
		uint16_t	subsystem,
		uint16_t	level
	)

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 pn_log_level_t and pn_log_subsystem_t for more details.

Note that log messages with a level of 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.

Parameters

[in]	logger	the logger
[in]	subsystem	bits representing subsystems to turn on trace for
[in]	level	bits representing log levels to turn on trace for

pn_logger_reset_mask()

void pn_logger_reset_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 pn_log_level_t and pn_log_subsystem_t for more details.

Note that log messages with a level of 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.

Parameters

[in]	logger	the logger
[in]	subsystem	bits representing subsystems to turn off trace for
[in]	level	bits representing log levels to turn off trace for

pn_logger_set_log_sink()

void pn_logger_set_log_sink	(	pn_logger_t *	logger,
		pn_log_sink_t	sink,
		intptr_t	sink_context
	)

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.

Parameters

[in]	logger	the logger
[in]	sink	the tracing function
[in]	sink_context	user specified context to pass into each call of the tracing callback

pn_logger_get_log_sink()

pn_log_sink_t pn_logger_get_log_sink

(

pn_logger_t *

logger

)

Get the tracing function used by a logger.

Parameters

[in]

logger

the logger

Returns

the tracing sink function used by a logger

pn_logger_get_log_sink_context()

intptr_t pn_logger_get_log_sink_context

(

pn_logger_t *

logger

)

Get the sink context used by a logger.

Parameters

[in]

logger

the logger

Returns

the sink context used by a logger

pn_logger_logf()

void pn_logger_logf	(	pn_logger_t *	logger,
		pn_log_subsystem_t	subsystem,
		pn_log_level_t	level,
		PN_PRINTF_FORMAT const char *	fmt,
			...
	)

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.

Parameters

[in]	logger	the logger
[in]	subsystem	the subsystem which is producing this log message
[in]	level	the log level of the log message
[in]	fmt	the printf formatted message to be logged