#include <stdarg.h>
#include "apr.h"
#include "apr_pools.h"

Macros
#define	paa_log(pool, msgid, level, format, ...)

#define	paa_log_error(pool, msgid, level, error_code, format, ...)

Typedefs
typedef enum paa_log_level_e	paa_log_level

typedef paa_log_level(*	paa_log_level_function) ()

typedef void(*	paa_log_function) (const char file, int line, apr_pool_t pool, const char msgid, paa_log_level level, apr_status_t error_code, const char format, va_list va_args)

Enumerations
enum	paa_log_level_e { PAA_OFF = 0, PAA_ERROR = 1, PAA_WARN = 2, PAA_INFO = 3, PAA_MONITOR = 4, PAA_DEBUG = 5, PAA_TRACE = 6 }

Functions
paa_log_level	paa_str_to_level (const char *level_str)

const char *	paa_level_str (paa_log_level level)

paa_log_level	paa_get_log_level ()

void	paa_log_msg (const char file, int line, apr_pool_t pool, const char msgid, paa_log_level level, apr_status_t error_code, const char format,...)

void	paa_set_log_functions (paa_log_function log_function, paa_log_level_function level_function)

Detailed Description

Header for the paa logging

Logging SDK messages to syslog:

While SDK consumers are free to handle log messages as they see fit, the logging functions and types should facilitate passing log messages to syslog. The comments in this header give some insight into how an SDK consumer would achieve this.

Macro Definition Documentation

#define paa_log	(	pool,
		msgid,
		level,
		format,
		...
	)

Value:

do {\
        paa_log_msg(__FILE__, __LINE__, pool, msgid, level, 0, format, ## __VA_ARGS__);\
    }while(0)

Convenience macro for paa_log_msg that includes the file and line without an error_code

#define paa_log_error	(	pool,
		msgid,
		level,
		error_code,
		format,
		...
	)

Value:

do{\
        paa_log_msg(__FILE__, __LINE__, pool, msgid, level, error_code, format, ## __VA_ARGS__);\
    }while(0)

Convenience macro for paa_log_msg that includes the file and line with an error_code

Typedef Documentation

typedef void(* paa_log_function) (const char *file, int line, apr_pool_t *pool, const char *msgid, paa_log_level level, apr_status_t error_code, const char *format, va_list va_args)

Logging function definition

Mapping the parameters to a syslog message:

the msgid is suitable for use as the syslog MSGID
the error_code, when non-zero, is suitable for use as a structured data element value
the format and va_args can be applied to generate the free-form message text

This function internally will call the function pointer passed to paa_set_log_function.

Parameters

file	the source file of the log message (FILE)
line	the line of the log message (LINE)
pool	the pool used to allocated any memory needed by the logging implementation – this can be NULL if memory allocation is not possible
msgid	the message id for the log message
level	the log level for the log message
error_code	the apr_status error_code. Can be 0.
format	a format string for the free-form message text
va_args	the arguments passed to a format string

typedef enum paa_log_level_e paa_log_level

Log levels for the logging facade. The order of severity is reflected by the order in the enum definition.

Mapping from paa_log_level to syslog:

PAA_ERROR => Error
PAA_WARN => Warning
PAA_INFO => Informational
PAA_MONITOR => Informational
PAA_DEBUG => Debug
PAA_TRACE => Debug

PAA_MONITOR most closely aligns with the Informational level, but the messages have a specific format, where data is separated by the | character. These messages contain statistics and auditing information relevant to a single HTTP request and response.

As an example, the data looks like:

{EVENT_STR}|{ELAPSED_TIME_IN_MS}|{EVENT_DATA_1}|{EVENT_DATA_2}

typedef paa_log_level(* paa_log_level_function) ()

Returns: the log level currently configured for the PAA module

Enumeration Type Documentation

enum paa_log_level_e

Log levels for the logging facade. The order of severity is reflected by the order in the enum definition.

Mapping from paa_log_level to syslog:

PAA_ERROR => Error
PAA_WARN => Warning
PAA_INFO => Informational
PAA_MONITOR => Informational
PAA_DEBUG => Debug
PAA_TRACE => Debug

PAA_MONITOR most closely aligns with the Informational level, but the messages have a specific format, where data is separated by the | character. These messages contain statistics and auditing information relevant to a single HTTP request and response.

As an example, the data looks like:

{EVENT_STR}|{ELAPSED_TIME_IN_MS}|{EVENT_DATA_1}|{EVENT_DATA_2}

Function Documentation

paa_log_level paa_get_log_level ( )

This function internally will call the function pointer passed to paa_set_log_level_function.

Returns: the log level currently configured for the PAA module

const char* paa_level_str ( paa_log_level level )

Converts a level to a string

Parameters

level the level

Returns: the log level as a string

void paa_log_msg	(	const char *	file,
		int	line,
		apr_pool_t *	pool,
		const char *	msgid,
		paa_log_level	level,
		apr_status_t	error_code,
		const char *	format,
			...
	)

This function internally will call the function pointer passed to paa_set_log_function.

Parameters

file	the source file of the log message (FILE)
line	the line of the log message (LINE)
pool	the pool used to allocated any memory needed by the logging implementation – this can be NULL if memory allocation is not possible
msgid	the message id for the log message
level	the log level for the log message
error_code	the apr_status error_code. Can be 0.
format	a format string for the free-form message text

void paa_set_log_functions	(	paa_log_function	log_function,
		paa_log_level_function	level_function
	)

Informs the SDK which logging functions to use. This function should be invoked with the appropriate function pointers before calling any other SDK methods.

log_function will only be invoked when paa_log_msg is called with a level that is less than or equal to the level returned by level_function. For example, if paa_log_msg is invoked with a level of PAA_DEBUG but level_function returns PAA_INFO, log_function will not be invoked.

Parameters

log_function	the paa_log_function
level_function	the paa_log_level_function

paa_log_level paa_str_to_level ( const char * level_str )

Converts a level string to a log level

Parameters

level_str the level string. Valid values are the name of values from paa_log_level enum without the preceding PAA_. For example, for a level_str of "INFO", this function will return PAA_INFO.

Returns: the log level. If the specified level_str is unknown, this function returns PAA_WARN.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation