API Reference

API Reference

Everything is declared in <coretrace/logger.hpp>, namespace coretrace. This page describes version 1.1.

Types

Type	Description
enum class Level { Debug, Info, Warn, Error }	Severity, in increasing order
struct LogEntry	A Level and the std::source_location of the call. Level converts to it implicitly, capturing the call site
struct Module	Module tag. Constructed explicitly from std::string_view or const char *, and not copied, so the string must outlive the log() call
enum class Color	Reset; styles Dim, Bold, Underline, Italic, Blink, Reverse, Hidden, Strike; foreground Black … White and Gray, BrightRed … BrightWhite; background BgBlack … BgWhite and BgGray, BgBrightRed … BgBrightWhite
using SinkFn = void (*)(const char *data, size_t size)	Output callback

Logging

Function	Description
log(LogEntry entry, std::string_view fmt, Args&&... args)	Formats with std::vformat and writes one line, if logging is enabled and the level passes
log(LogEntry entry, Module mod, std::string_view fmt, Args&&... args)	Same, with a module tag; also applies the module filter

Invalid format strings write the fallback line described in Output Format. Empty messages write nothing.

Configuration

Function	Description
void enable_logging() / void disable_logging()	Turn output on or off. Off by default
bool log_is_enabled()	Current state
void set_prefix(std::string_view prefix)	Line tag, default ==ct==; copied and truncated to 63 characters
void set_min_level(Level level) / Level min_level()	Minimum level, default Info. Takes precedence over CT_LOG_LEVEL
bool enable_module(std::string_view name)	Adds a name to the filter. Returns false for an empty name, a name of 32 characters or more, or a full table (32 names)
void disable_module(std::string_view name)	Removes a name; the filter stays active
void enable_all_modules()	Clears the filter
bool module_is_enabled(std::string_view name)	Whether a message tagged name would pass
void set_thread_safe(bool enabled)	Serialized output, on by default. See Sinks and Threading
void set_sink(SinkFn fn) / void reset_sink()	Redirect output, or restore stderr. nullptr means stderr
void set_timestamps(bool enabled)	UTC timestamps, off by default
void set_source_location(bool enabled)	file:line after the level, off by default

Getters (min_level(), module_is_enabled()) read CT_LOG_LEVEL and CT_DEBUG first if no earlier call has done it.

Colors

Function	Description
std::string_view color(Color c)	ANSI sequence, or empty when colors are off
std::string_view level_label(Level level)	"DEBUG", "INFO", "WARN" or "ERROR"
std::string_view level_color(Level level)	Color sequence of a level, or empty

Low-level output

These functions write to the current sink without serialization, even in thread-safe mode.

Function	Description
void write_raw(const char *data, size_t size)	Raw bytes. Does nothing for nullptr or size 0
void write_str(std::string_view value)	A string
void write_dec(size_t value)	Decimal, without heap allocation
void write_hex(uintptr_t value)	Lowercase hexadecimal with 0x, without leading zeros (0x0 for 0)
void write_prefix(Level level)	|PID| prefix [LEVEL] , without timestamp or source location

System information

Function	Description
int pid()	Process ID, asked of the system on each call: a child of fork() gets its own
unsigned long long thread_id()	OS thread ID: gettid on Linux, pthread_threadid_np on macOS, GetCurrentThreadId on Windows

Internal

write_log_line(), write_format_error() and init_once() are declared in the header because the log() templates call them. They are not meant to be called directly.