Application-level structured logging. More...

#include <stddef.h>
#include <stdbool.h>
#include <stdarg.h>

Include dependency graph for logger.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	cwist_logger

Typedefs
typedef struct cwist_logger	cwist_logger

Enumerations
enum	cwist_log_level_t { CWIST_LOG_DEBUG , CWIST_LOG_INFO , CWIST_LOG_WARN , CWIST_LOG_ERROR }

Functions
Lifecycle
cwist_logger *	cwist_logger_create (const char *name)
	Create a logger.

void	cwist_logger_destroy (cwist_logger *log)
	Destroy a logger.

Configuration
void	cwist_logger_set_level (cwist_logger *log, cwist_log_level_t level)
	Set the minimum log level.

void	cwist_logger_set_colors (cwist_logger *log, bool enabled)
	Enable or disable colored output.

Logging
void	cwist_logger_log (cwist_logger log, cwist_log_level_t level, const char fmt,...)
	Write a log message.

void	cwist_logger_debug (cwist_logger log, const char fmt,...)
	Write a debug message.

void	cwist_logger_info (cwist_logger log, const char fmt,...)
	Write an info message.

void	cwist_logger_warn (cwist_logger log, const char fmt,...)
	Write a warning message.

void	cwist_logger_error (cwist_logger log, const char fmt,...)
	Write an error message.

Async output
Opt-in background writer for cwist_logger_* lines and the built-in access-log middleware (cwist_mw_access_log()). Callers format the line and queue it; one writer thread does the write() calls, so the request path makes no syscall. Lines stay whole and in order per stream, a full buffer makes the caller wait (nothing is dropped), and a line larger than the buffer is written synchronously.
bool	cwist_log_async_start (size_t buffer_bytes)
	Start the background log writer.

void	cwist_log_async_flush (void)
	Block until every line queued so far has been written.

void	cwist_log_async_stop (void)
	Write out queued lines, stop the writer and return to synchronous output.

bool	cwist_log_async_active (void)
	Whether the background log writer is active.

Detailed Description

Application-level structured logging.

Definition in file logger.h.

Typedef Documentation

◆ cwist_logger

typedef struct cwist_logger cwist_logger

Enumeration Type Documentation

◆ cwist_log_level_t

enum cwist_log_level_t

Enumerator
CWIST_LOG_DEBUG
CWIST_LOG_INFO
CWIST_LOG_WARN
CWIST_LOG_ERROR

Definition at line 13 of file logger.h.

Function Documentation

◆ cwist_log_async_active()

bool cwist_log_async_active ( void )

Whether the background log writer is active.

Returns: true between a successful cwist_log_async_start() and cwist_log_async_stop().

Definition at line 256 of file log_async.c.

References cap.

◆ cwist_log_async_flush()

void cwist_log_async_flush ( void )

Block until every line queued so far has been written.

Definition at line 221 of file log_async.c.

References cap.

◆ cwist_log_async_start()

bool cwist_log_async_start ( size_t buffer_bytes )

Start the background log writer.

Parameters

buffer_bytes Buffer size per stream (stdout and stderr); 0 selects 256 KiB.

Returns: true when async logging is active, false when it could not start (logging then stays synchronous).

Note: Lines still queued at exit() are written by an atexit hook. Call cwist_log_async_flush() before _exit(). A forked child (CWIST_WORKERS) starts its own writer on its first line.

Start the background log writer.

Parameters

buffer_bytes Ring size per stream (stdout and stderr); 0 selects 256 KiB.

Returns: true when async logging is active (also when it already was), false when memory or the thread could not be had; logging then stays synchronous.

Note: Covers cwist_logger_* and the built-in access-log middleware. Lines queued at exit() are written by an atexit hook; call cwist_log_async_stop() or cwist_log_async_flush() before _exit() or a crash-prone section if the last lines matter.

Definition at line 176 of file log_async.c.

References cap, cwist_alloc(), cwist_free(), LOG_ASYNC_DEFAULT_BYTES, and LOG_ASYNC_STREAMS.

◆ cwist_log_async_stop()

void cwist_log_async_stop ( void )

Write out queued lines, stop the writer and return to synchronous output.

Definition at line 229 of file log_async.c.

References cap, cwist_free(), and LOG_ASYNC_STREAMS.

◆ cwist_logger_create()

cwist_logger * cwist_logger_create ( const char * name )

Create a logger.

Parameters

name	Logger name copied into the instance; NULL selects "cwist".

Returns: Newly allocated logger on success, NULL on allocation failure.

Note: Ownership of the returned logger transfers to the caller; release it with cwist_logger_destroy().

Definition at line 32 of file logger.c.

References cap, cwist_alloc(), cwist_free(), CWIST_LOG_INFO, cwist_strdup(), cwist_logger::level, cwist_logger::name, and cwist_logger::use_colors.

Referenced by cwist_app_create().

◆ cwist_logger_debug()

void cwist_logger_debug	(	cwist_logger *	log,
		const char *	fmt,
			...
	)

Write a debug message.

Parameters

log	Logger to log through; NULL is safely ignored.
fmt	printf-style format string.

Definition at line 154 of file logger.c.

References cap, and CWIST_LOG_DEBUG.

◆ cwist_logger_destroy()

void cwist_logger_destroy ( cwist_logger * log )

Destroy a logger.

Parameters

log	Logger to free; NULL is safely ignored.

Definition at line 48 of file logger.c.

References cwist_free(), and cwist_logger::name.

Referenced by cwist_app_destroy().

◆ cwist_logger_error()

void cwist_logger_error	(	cwist_logger *	log,
		const char *	fmt,
			...
	)

Write an error message.

Parameters

log	Logger to log through; NULL is safely ignored.
fmt	printf-style format string.

Definition at line 187 of file logger.c.

References cap, and CWIST_LOG_ERROR.

◆ cwist_logger_info()

void cwist_logger_info	(	cwist_logger *	log,
		const char *	fmt,
			...
	)

Write an info message.

Parameters

log	Logger to log through; NULL is safely ignored.
fmt	printf-style format string.

Definition at line 165 of file logger.c.

References cap, and CWIST_LOG_INFO.

◆ cwist_logger_log()

void cwist_logger_log	(	cwist_logger *	log,
		cwist_log_level_t	level,
		const char *	fmt,
			...
	)

Write a log message.

Parameters

log	Logger to log through; NULL is safely ignored.
level	Level of the message; messages below the logger's level are suppressed.
fmt	printf-style format string.

Note: The message is written to stdout for levels below WARN and to stderr otherwise, with a timestamp, level tag, and logger name prefix, followed by a newline. The shared FILE streams are not locked across the prefix and the message, so lines from concurrent threads may interleave. In the sync fallback each line is still one fwrite(3) call (line-at-a-time write granularity), but stdio block-buffers the bytes, so lines are delivered in batches rather than per line; a TTY destination stays line-buffered. Call cwist_log_async_start() for immediate per-line delivery.

Definition at line 143 of file logger.c.

References cap.

◆ cwist_logger_set_colors()

void cwist_logger_set_colors	(	cwist_logger *	log,
		bool	enabled
	)

Enable or disable colored output.

Parameters

log	Logger to configure; NULL is safely ignored.
enabled	true to colorize level prefixes, false for plain output.

Definition at line 66 of file logger.c.

References cwist_logger::use_colors.

◆ cwist_logger_set_level()

void cwist_logger_set_level	(	cwist_logger *	log,
		cwist_log_level_t	level
	)

Set the minimum log level.

Parameters

log	Logger to configure; NULL is safely ignored.
level	New minimum level; messages below it are suppressed.

Definition at line 58 of file logger.c.

References cwist_logger::level.

◆ cwist_logger_warn()

void cwist_logger_warn	(	cwist_logger *	log,
		const char *	fmt,
			...
	)

Write a warning message.

Parameters

log	Logger to log through; NULL is safely ignored.
fmt	printf-style format string.

Definition at line 176 of file logger.c.

References cap, and CWIST_LOG_WARN.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ cwist_logger

Enumeration Type Documentation

◆ cwist_log_level_t

Function Documentation

◆ cwist_log_async_active()

◆ cwist_log_async_flush()

◆ cwist_log_async_start()

◆ cwist_log_async_stop()

◆ cwist_logger_create()

◆ cwist_logger_debug()

◆ cwist_logger_destroy()

◆ cwist_logger_error()

◆ cwist_logger_info()

◆ cwist_logger_log()

◆ cwist_logger_set_colors()

◆ cwist_logger_set_level()

◆ cwist_logger_warn()