Logging

Macros
#define	BJ_MAXIMUM_LOG_LEN   120u
#define	bj_log_msg(LEVEL, ...)
#define	bj_trace(...)
#define	bj_debug(...)
#define	bj_info(...)
#define	bj_warn(...)
#define	bj_err(...)
#define	bj_fatal(...)

Typedefs
typedef enum bj_log_level	bj_log_level

Enumerations
enum	bj_log_level {   BJ_LOG_TRACE , BJ_LOG_DEBUG , BJ_LOG_INFO , BJ_LOG_WARN ,   BJ_LOG_ERROR , BJ_LOG_FATAL }

Functions
const char *	bj_get_log_level_string (int level)
void	bj_set_log_level (int level)
int	bj_get_log_level (void)
size_t	bj_log_message (int level, const char *file, int line, const char *format,...)

Detailed Description

Severity-filtered structured logging.

Banjo applications and the library itself log through one shared channel. Six severity levels are defined in bj_log_level (TRACE, DEBUG, INFO, WARN, ERROR, FATAL). At runtime only messages at or above the threshold set by bj_set_log_level are emitted; everything below is dropped at the call site, so leaving trace logs in shipped code costs nothing when the threshold is higher.

The fast path: macros per level

Use the per-level macros (bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal) over the generic bj_log_msg / bj_log_message. They take printf-style arguments:

bj_info("server listening on port %d", port);
bj_err("read failed: %s", bj_error_message(err));

In debug builds, the macros also emit the source file and line (rendered as "FILE:LINE" between the level and the message). In release builds those are stripped to keep the binary lean.

Format

A complete log line looks like TIME LEVEL: (SOURCE) MESSAGE, e.g. 12:23:34 WARN: logging.c:27 Warning level message. The maximum line length is fixed at BJ_MAXIMUM_LOG_LEN; messages longer than that are truncated, with header components (level, time, source) dropped in reverse priority order to keep the message intact.

Set BANJO_CONFIG_LOG_COLOR at build time to colourise level names (and source location in debug builds) using ANSI codes when the terminal supports it.

See also

logging.c for a runnable demo.

Macro Definition Documentation

bj_debug

#define bj_debug

(

...

)

Value:

bj_log_msg(DEBUG, __VA_ARGS__)

Log a message using the BJ_LOG_DEBUG level.

The function effectively calls bj_log_message, forwarding arguments to format the input string.

This function is preferred over calling bj_log_msg or bj_log_message directly for clarity.

Parameters

...	The string formatting, forwarded to the last arguments of bj_log_message.

See also

bj_trace, bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal. Log using BJ_LOG_DEBUG level.

Definition at line 127 of file log.h.

bj_err

#define bj_err

(

...

)

Value:

bj_log_msg(ERROR, __VA_ARGS__)

Log a message using the BJ_LOG_ERROR level.

The function effectively calls bj_log_message, forwarding arguments to format the input string.

This function is preferred over calling bj_log_msg or bj_log_message directly for clarity.

Parameters

...	The string formatting, forwarded to the last arguments of bj_log_message.

See also

bj_warn, bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal. Log using BJ_LOG_ERROR level.

Examples

handling_errors.c, logging.c, net_tcp_client.c, net_tcp_nonblocking.c, net_tcp_server.c, net_tcp_timeout.c, net_udp_broadcast_recv.c, net_udp_broadcast_send.c, net_udp_client.c, net_udp_server.c, and pong.c.

Definition at line 169 of file log.h.

Referenced by main(), and setup().

bj_fatal

#define bj_fatal

(

...

)

Value:

bj_log_msg(FATAL, __VA_ARGS__)

Log a message using the BJ_LOG_FATAL level.

The function effectively calls bj_log_message, forwarding arguments to format the input string.

This function is preferred over calling bj_log_msg or bj_log_message directly for clarity.

Parameters

...	The string formatting, forwarded to the last arguments of bj_log_message.

See also

bj_err, bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal. Log using BJ_LOG_FATAL level.

Definition at line 183 of file log.h.

bj_info

#define bj_info

(

...

)

Value:

bj_log_msg(INFO, __VA_ARGS__)

Log a message using the BJ_LOG_INFO level.

The function effectively calls bj_log_message, forwarding arguments to format the input string.

This function is preferred over calling bj_log_msg or bj_log_message directly for clarity.

Parameters

...	The string formatting, forwarded to the last arguments of bj_log_message.

See also

bj_debug, bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal. Log using BJ_LOG_INFO level.

Examples

cli.c, event_callbacks.c, event_polling.c, handling_errors.c, logging.c, net_tcp_client.c, net_tcp_nonblocking.c, net_tcp_server.c, net_tcp_timeout.c, net_udp_broadcast_recv.c, net_udp_broadcast_send.c, net_udp_client.c, net_udp_server.c, pixel_mode.c, random.c, template.c, and template_callbacks.c.

Definition at line 141 of file log.h.

Referenced by button_callback(), cursor_callback(), demonstrate_error_copy(), demonstrate_error_matching(), demonstrate_zero_cost(), display_value(), enter_callback(), initialize_server(), key_callback(), main(), resize_callback(), resize_callback(), step(), step(), teardown(), and teardown().

bj_log_msg

#define bj_log_msg	(		LEVEL,
			... )

Value:

bj_log_message(BJ_LOG_ ## LEVEL, 0, 0, __VA_ARGS__)

Log a message using the given level LEVEL.

Any integer value can be used for LEVEL, but usually any of BJ_LOG_TRACE, BJ_LOG_DEBUG, BJ_LOG_INFO, BJ_LOG_WARN, BJ_LOG_ERROR or BJ_LOG_FATAL is used.

When a message is sent with a given level, it will be reported only if the value set with bj_set_log_level is at least the same value.

The function effectively calls bj_log_message, forwarding arguments to format the input string.

Parameters

LEVEL	The log level to report the message in.
...	Arguments forwarded to bj_log_message.

See also

bj_log_message, bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal.

Examples

logging.c.

Definition at line 96 of file log.h.

Referenced by main().

BJ_MAXIMUM_LOG_LEN

#define BJ_MAXIMUM_LOG_LEN   120u

Maximum length of log messages.

Log messages, including header information such as timestamp and log level, cannot have a size in bytes larger than BJ_MAXIMUM_LOG_LEN, excluding the null character. In case a message is longer than this limit, the content is truncated in order of priority as described in bj_log_message.

Definition at line 60 of file log.h.

bj_trace

#define bj_trace

(

...

)

Value:

bj_log_msg(TRACE, __VA_ARGS__)

Log a message using the BJ_LOG_TRACE level.

The function effectively calls bj_log_message, forwarding arguments to format the input string.

This function is preferred over calling bj_log_msg or bj_log_message directly for clarity.

Parameters

...	The string formatting, forwarded to the last arguments of bj_log_message.

See also

bj_log_msg, bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal. Log using BJ_LOG_TRACE level.

Examples

stopwatch.c, and time.c.

Definition at line 113 of file log.h.

Referenced by main().

bj_warn

#define bj_warn

(

...

)

Value:

bj_log_msg(WARN, __VA_ARGS__)

Log a message using the BJ_LOG_WARN level.

The function effectively calls bj_log_message, forwarding arguments to format the input string.

This function is preferred over calling bj_log_msg or bj_log_message directly for clarity.

Parameters

...	The string formatting, forwarded to the last arguments of bj_log_message.

See also

bj_info, bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal. Log using BJ_LOG_WARN level.

Examples

logging.c.

Definition at line 155 of file log.h.

Referenced by main().

Typedef Documentation

bj_log_level

typedef enum bj_log_level bj_log_level

Definition at line 75 of file log.h.

Enumeration Type Documentation

bj_log_level

enum bj_log_level

Log Levels.

Level values are ordered from 0.

Enumerator
BJ_LOG_TRACE	Fine-grained diagnostic details.
BJ_LOG_DEBUG	Detailed information for debugging.
BJ_LOG_INFO	Informational messages about execution.
BJ_LOG_WARN	Warnings for potential issues.
BJ_LOG_ERROR	Errors preventing correct function.
BJ_LOG_FATAL	Critical errors leading to termination.

Definition at line 66 of file log.h.

Function Documentation

bj_get_log_level()

int bj_get_log_level

(

void

)

Gets the current log level set by bj_set_log_level.

Returns

An integer value describing the current log level.

Examples

logging.c.

Referenced by main().

bj_get_log_level_string()

const char * bj_get_log_level_string

(

int

level

)

Returns a string describing the given level.

The function is only valid if called with BJ_LOG_TRACE, BJ_LOG_DEBUG, BJ_LOG_INFO, BJ_LOG_WARN, BJ_LOG_ERROR or BJ_LOG_FATAL.

The returned value is owned by the callee.

Parameters

level

The log level to get the description from.

Returns

A C-String describing level.

bj_log_message()

size_t bj_log_message	(	int	level,
		const char *	file,
		int	line,
		const char *	format,
			... )

Generic message reporting function.

Sends a message using the given level. Message will only be reported if level is at least the value set as a parameter to bj_set_log_level (or BJ_LOG_TRACE if never called).

The more convenient functions bj_log_msg, bj_trace, ... should be used for simplicity.

The string formatting follows standard printf signature and behaviour.

Parameters

level	The log level the message is reported in.
file	The file name the message is reported from.
line	The line number the message is reported from.
format,...	The formatted string to report.

Returns

The actual number of characters written, excluding the null-terminating symbol.

Format and Behaviour

The log message will have the following format:

• TIME LEVEL: (SOURCE) MESSAGE Where:
• TIME is in the format "HH:MM:SS" and takes 8 characters
• LEVEL, in square brackets, is the result of calling bj_get_log_level_string. It takes up to 4 to 5 characters.
• SOURCE is in the format "FILE:LINE" and takes an undetermined number of characters. This is only present in a debug build.
• MESSAGE is the result of calling snprintf(format, ...) and the number of character varies.

For example: 12:23:34 WARN: logging.c:27 Warning level message

The maximum length a log message will take is hardcoded to the value set for BJ_MAXIMUM_LOG_LEN.

A first buffer is filled in with the expansion of the message. This message is truncated to fit the BJ_MAXIMUM_LOG_LEN characters limit entirely. If this limit is already reached, the message is logged as-is.

Then, in the order of below priority:

• If BJ_CONFIG_LOG_COLOR is set and but is not enough space for coloured source (Debug only), SOURCE is not coloured.
• If BJ_CONFIG_LOG_COLOR is set and but is not enough space for coloured level, LEVEL is not coloured.
• If there is not enough space left for TIME, it is not present.
• If there is not enough space for SOURCE (Debug only), it is not present.
• If there is not enough space for LEVEL, it is not present.

See also

bj_log_msg, bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal

bj_set_log_level()

void bj_set_log_level

(

int

level

)

Sets the default log level.

Once set, any call to bj_log_message, bj_log_msg and helper macros will only report a message is its level is at least level.

Parameters

level

The level to set.

If not set, default is BJ_LOG_TRACE.

Examples

logging.c.

Referenced by main().