Logging

struct ULog

Logger object.

Public Members

ulog_level level: Log level.

bool color: Whether color output is enabled.

UOStream *stream: Logger output stream.

void *state: Logger state.

ulib_ret (*handler)(struct ULog *log, ULogEvent const *event)

Function that handles log events.

Param log:: Logger object.
Param event:: Log event.
Return:: Return code.

enum ulog_level_builtin

Builtin log levels.

Values:

enumerator ULOG_TRACE: Trace level.

enumerator ULOG_DEBUG: Debug level.

enumerator ULOG_PERF: Performance level.

enumerator ULOG_INFO: Info level.

enumerator ULOG_WARN: Warning level.

enumerator ULOG_ERROR: Error level.

enumerator ULOG_FATAL: Fatal level.

typedef unsigned ulog_level: Log level.

ULOG_ALL: Marker level for loggers that log everything.

ULOG_DISABLED: Marker level for disabled loggers.

struct ULogMsg

#include “ulog.h”

Log message.

Public Members

char const *fmt: Format string.

va_list args: Format arguments.

struct ULogTag

#include “ulog.h”

Log tag.

Public Members

char const *string: Tag string.

char const *color: Tag color.

struct ULogEvent

#include “ulog.h”

Log event.

Public Members

ulog_level level: Log level.

USrcLoc loc: Source code location.

ULogMsg msg: Event message.

void const *data: Event data.

ULog *const ulog_main: The main logger.

UString ulog_level_to_string(ulog_level level)

Returns the string representation of the specified log level.

Note

You must not call ustring_deinit on the returned string.

Parameters:

level – Log level.

Returns:

String representation of the log level.

ulog_level ulog_level_from_string(UString string)

Converts the specified string to a log level.

Note

The match is case-insensitive and based on the beginning of the string. For example, “info” will match ULOG_INFO, and so will “INFO”, “Information”, etc.

Parameters:

string – String representation of the log level.

Returns:

Log level corresponding to the specified string. If the string does not match any known log level, returns ULOG_DISABLED.

ULog ulog_default(void)

Returns a logger object initialized with the default settings.

Returns:: Logger object.

bool ulog_enabled(ULog *log, ulog_level level)

Checks whether the logger handles events at the specified log level.

Parameters:

log – Logger object.
level – Log level.

Returns:

True if the logger handles events at the specified log level, false otherwise.

void ulog_disable(ULog *log)

Disables event handling for the specified logger.

Note

Set the log level to anything other than ULOG_DISABLED to re-enable event handling.

Parameters:

log – Logger object.

ulib_ret ulog(ULog *log, ulog_level level, void *data, char const *fmt, ...)

Raises a log event, passing some user data.

Parameters:

log – Logger object.
level – Event level.
data – User data.
fmt – Message format string.
... – Message format arguments.

Returns:

Return code.

ulib_ret ulog_trace(char const *fmt, ...)

Same as ulog(ulog_main, ULOG_TRACE, NULL, fmt, ...).

Parameters:

fmt – Message format string.
... – Message format arguments.

Returns:

Return code.

ulib_ret ulog_debug(char const *fmt, ...)

Same as ulog(ulog_main, ULOG_DEBUG, NULL, fmt, ...).

Parameters:

fmt – Message format string.
... – Message format arguments.

Returns:

Return code.

ulib_ret ulog_info(char const *fmt, ...)

Same as ulog(ulog_main, ULOG_INFO, NULL, fmt, ...).

Parameters:

fmt – Message format string.
... – Message format arguments.

Returns:

Return code.

ulib_ret ulog_warn(char const *fmt, ...)

Same as ulog(ulog_main, ULOG_WARN, NULL, fmt, ...).

Parameters:

fmt – Message format string.
... – Message format arguments.

Returns:

Return code.

ulib_ret ulog_error(char const *fmt, ...)

Same as ulog(ulog_main, ULOG_ERROR, NULL, fmt, ...).

Parameters:

fmt – Message format string.
... – Message format arguments.

Returns:

Return code.

ulib_ret ulog_fatal(char const *fmt, ...)

Same as ulog(ulog_main, ULOG_FATAL, NULL, fmt, ...).

Parameters:

fmt – Message format string.
... – Message format arguments.

Returns:

Return code.

ulib_ret ulog_ns(utime_ns const *nanos, char const *fmt, ...)

Same as ulog(ulog_main, ULOG_PERF, nanos, fmt, ...).

Parameters:

nanos – Elapsed time in nanoseconds.
fmt – Message format string.
... – Message format arguments.

Returns:

Return code.

ulib_ret ulog_write_event(ULog *log, ULogEvent const *event)

Writes the specified event to the logger’s output stream.

Parameters:

log – Logger object.
event – Log event.

Returns:

Return code.

ulib_ret ulog_write_header(ULog *log, ULogEvent const *event)

Writes the header of the specified event to the logger’s output stream.

Note

The header consists of the date, time, and log level.

Parameters:

log – Logger object.
event – Log event.

Returns:

Return code.

ulib_ret ulog_write_footer(ULog *log, ULogEvent const *event)

Writes the footer of the specified event to the logger’s output stream.

Note

The footer consists of the log message and additional metadata based on the debug level.

Parameters:

log – Logger object.
event – Log event.

Returns:

Return code.

ulib_ret ulog_write_msg(ULog *log, ULogMsg msg)

Writes the specified message to the logger’s output stream.

Parameters:

log – Logger object.
msg – Log message.

Returns:

Return code.

ulib_ret ulog_write_date(ULog *log)

Writes the current date and time to the logger’s output stream.

Parameters:

log – Logger object.

Returns:

Return code.

ulib_ret ulog_write_level(ULog *log, ulog_level level)

Writes the specified log level to the logger’s output stream.

Parameters:

log – Logger object.
level – Log level.

Returns:

Return code.

ulib_ret ulog_write_tag(ULog *log, ULogTag tag)

Writes the specified tag to the logger’s output stream.

Parameters:

log – Logger object.
tag – Tag.

Returns:

Return code.

ulib_ret ulog_write_loc(ULog *log, USrcLoc loc)

Writes the specified source code location to the logger’s output stream.

Parameters:

log – Logger object.
loc – Source code location.

Returns:

Return code.

ulib_ret ulog_write_elapsed(ULog *log, utime_ns elapsed)

Writes elapsed time to the logger’s output stream.

Parameters:

log – Logger object.
elapsed – Elapsed time.

Returns:

Return code.

ulib_ret ulog_write_color(ULog *log, char const *color, char const *fmt, ...)

Writes a formatted string in the specified color to the logger’s output stream.

Parameters:

log – Logger object.
color – ANSI color escape code.
fmt – Format string.
... – Format arguments.

Returns:

Return code.

ulib_ret ulog_write_space(ULog *log)

Writes a space to the logger’s output stream.

Parameters:

log – Logger object.

Returns:

Return code.

ulib_ret ulog_write_newline(ULog *log)

Writes a newline to the logger’s output stream.

Parameters:

log – Logger object.

Returns:

Return code.

ulog_elapsed(log, ...)

Measures and logs the time elapsed between the start and end of a block of code.

Usage example:

ulog_elapsed(ulog_main, "Block time") {
    // Code to measure.
}

Parameters:

log – Logger object.
... – Format string and arguments.

ulog_perf(...)

Same as ulog_elapsed(ulog_main, ...).

Usage example:

ulog_perf("Block time") {
    // Code to measure.
}

Parameters:

... – Format string and arguments.

Colors

ANSI color codes

UCOLOR_BLK: Black text.

UCOLOR_RED: Red text.

UCOLOR_GRN: Green text.

UCOLOR_YEL: Yellow text.

UCOLOR_BLU: Blue text.

UCOLOR_MAG: Magenta text.

UCOLOR_CYN: Cyan text.

UCOLOR_WHT: White text.

UCOLOR_BBLK: Bold black text.

UCOLOR_BRED: Bold red text.

UCOLOR_BGRN: Bold green text.

UCOLOR_BYEL: Bold yellow text.

UCOLOR_BBLU: Bold blue text.

UCOLOR_BMAG: Bold magenta text.

UCOLOR_BCYN: Bold cyan text.

UCOLOR_BWHT: Bold white text.

UCOLOR_UBLK: Underlined black text.

UCOLOR_URED: Underlined red text.

UCOLOR_UGRN: Underlined green text.

UCOLOR_UYEL: Underlined yellow text.

UCOLOR_UBLU: Underlined blue text.

UCOLOR_UMAG: Underlined magenta text.

UCOLOR_UCYN: Underlined cyan text.

UCOLOR_UWHT: Underlined white text.

UCOLOR_BLKB: Black background.

UCOLOR_REDB: Red background.

UCOLOR_GRNB: Green background.

UCOLOR_YELB: Yellow background.

UCOLOR_BLUB: Blue background.

UCOLOR_MAGB: Magenta background.

UCOLOR_CYNB: Cyan background.

UCOLOR_WHTB: White background.

UCOLOR_BLKHB: High intensity black background.

UCOLOR_REDHB: High intensity red background.

UCOLOR_GRNHB: High intensity green background.

UCOLOR_YELHB: High intensity yellow background.

UCOLOR_BLUHB: High intensity blue background.

UCOLOR_MAGHB: High intensity magenta background.

UCOLOR_CYNHB: High intensity cyan background.

UCOLOR_WHTHB: High intensity white background.

UCOLOR_HBLK: High intensity black text.

UCOLOR_HRED: High intensity red text.

UCOLOR_HGRN: High intensity green text.

UCOLOR_HYEL: High intensity yellow text.

UCOLOR_HBLU: High intensity blue text.

UCOLOR_HMAG: High intensity magenta text.

UCOLOR_HCYN: High intensity cyan text.

UCOLOR_HWHT: High intensity white text.

UCOLOR_BHBLK: Bold high intensity black text.

UCOLOR_BHRED: Bold high intensity red text.

UCOLOR_BHGRN: Bold high intensity green text.

UCOLOR_BHYEL: Bold high intensity yellow text.

UCOLOR_BHBLU: Bold high intensity blue text.

UCOLOR_BHMAG: Bold high intensity magenta text.

UCOLOR_BHCYN: Bold high intensity cyan text.

UCOLOR_BHWHT: Bold high intensity white text.

UCOLOR_RST: Reset all attributes.

Semantic colors

UCOLOR_DIM: Color for dim text.

UCOLOR_OK: Color for success messages.

UCOLOR_FAIL: Color for failure messages.

UCOLOR_TRACE: Color for trace messages.

UCOLOR_DEBUG: Color for debug messages.

UCOLOR_PERF: Color for performance messages.

UCOLOR_INFO: Color for informational messages.

UCOLOR_WARN: Color for warning messages.

UCOLOR_ERROR: Color for error messages.

UCOLOR_FATAL: Color for fatal error messages.