spdlog initialization, logger factory, and formatting utilities. More...

#include <entropic/types/logging.h>
#include <spdlog/sinks/basic_file_sink.h>
#include <spdlog/sinks/stdout_color_sinks.h>
#include <spdlog/sinks/sink.h>
#include <algorithm>
#include <array>
#include <atomic>
#include <filesystem>
#include <mutex>
#include <unordered_map>
#include <unordered_set>

Include dependency graph for logging.cpp:

Go to the source code of this file.

Classes
class	entropic::log::HandleAwareSink
	Per-handle file sink dispatcher (installed on default logger). More...

Namespaces
namespace	entropic
	Activate model on GPU (WARM → ACTIVE).

Functions
ENTROPIC_EXPORT void	entropic::log::init (spdlog::level::level_enum level=spdlog::level::info)
	Initialize the logging subsystem.

ENTROPIC_EXPORT void	entropic::log::add_file_sink (const std::filesystem::path &path)
	Add a file sink to all loggers (truncated per run).

ENTROPIC_EXPORT std::shared_ptr< spdlog::logger >	entropic::log::get (const std::string &name)
	Get or create a named logger.

ENTROPIC_EXPORT void	entropic::log::set_console_enabled (bool enabled)
	Enable or disable the stderr console sink process-wide.

static void	entropic::log::remove_console_sink ()
	Set up session logging for a project directory.

ENTROPIC_EXPORT void	entropic::log::setup_session (const std::filesystem::path &log_dir)
	Set up session logging for a project directory.

void	entropic::log::escape_ansi (const std::string &text, size_t &i, std::string &result)
	Consume an ANSI CSI sequence starting at the ESC byte.

static const std::array< const char *, 256 > &	entropic::log::escape_table ()
	256-entry table mapping bytes to escape strings (nullptr = passthrough).

bool	entropic::log::escape_char (char c, std::string &result)
	Append escaped form of c if special, else return false.

ENTROPIC_EXPORT std::string	entropic::log::escape_content (const std::string &text)
	Escape content for safe spdlog formatting.

ENTROPIC_EXPORT void	entropic::log::log_content (const std::shared_ptr< spdlog::logger > &logger, spdlog::level::level_enum level, const std::string &label, const std::string &text)
	Log full content with escaping applied.

ENTROPIC_EXPORT void	entropic::log::log_timing (const std::shared_ptr< spdlog::logger > &logger, const std::string &label, double ms)
	Log a timing measurement.

ENTROPIC_EXPORT void	entropic::log::log_tokens (const std::shared_ptr< spdlog::logger > &logger, int count, double time_ms)
	Log token count with throughput.

ENTROPIC_EXPORT void	entropic::log::log_decision (const std::shared_ptr< spdlog::logger > &logger, const std::string &label, const std::string &key, const std::string &value)
	Log a decision/routing event.

ENTROPIC_EXPORT void	entropic::log::register_handle_log (int handle_id, const std::filesystem::path &log_dir)
	gh#59 (v2.3.1): register a per-handle session.log file.

ENTROPIC_EXPORT void	entropic::log::unregister_handle_log (int handle_id)
	gh#59 (v2.3.1): release a handle's session.log file sink.

ENTROPIC_EXPORT int	entropic::log::current_handle_id ()
	gh#59 (v2.3.1): query the current thread's handle_id.

Variables
static std::once_flag	entropic::log::s_init_flag

static std::shared_ptr< spdlog::sinks::stderr_color_sink_mt >	entropic::log::s_sink

static thread_local int	entropic::log::t_current_handle_id = 0
	Thread-local current handle id (0 = no scope active).

static std::shared_ptr< HandleAwareSink >	entropic::log::s_dispatcher

static std::atomic< bool >	entropic::log::s_console_disabled {false}

static std::mutex	entropic::log::s_session_paths_mu

static std::unordered_set< std::string >	entropic::log::s_session_paths

Detailed Description

spdlog initialization, logger factory, and formatting utilities.

Version: 2.0.7

Definition in file logging.cpp.

Function Documentation

◆ add_file_sink()

void entropic::log::add_file_sink ( const std::filesystem::path & path )

Add a file sink to all loggers (truncated per run).

Add a rotating file sink to all loggers.

Creates the parent directory, opens the file (truncating any existing content), adds the sink to the default logger, and applies it to every logger already registered. Loggers created after this call inherit the sink automatically via get().

Parameters

path	Log file path.

Version: 2.0.1

Creates the log directory, adds the sink to the default logger, then walks every registered logger and adds the same sink. Future loggers created via get() inherit it automatically.

Parameters

path	Log file path.
max_size	Max bytes before rotation.
max_files	Rotated files to keep. @utility

Version: 2.0.1

Definition at line 179 of file logging.cpp.

◆ current_handle_id()

int entropic::log::current_handle_id ( )

gh#59 (v2.3.1): query the current thread's handle_id.

gh#59 public entry — see header.

Returns 0 if no HandleLogScope is active on this thread. Mostly for tests; production code should rely on the dispatcher routing.

Version: 2.3.1

@utility

Version: 2.3.1

Definition at line 540 of file logging.cpp.

◆ escape_ansi()

void entropic::log::escape_ansi	(	const std::string &	text,
		size_t &	i,
		std::string &	result
	)

Consume an ANSI CSI sequence starting at the ESC byte.

Writes "[ESC<params>]" into result. Advances i past the sequence terminator 'm'. If the sequence is malformed, writes "[ESC]" and leaves i on the ESC byte.

Parameters

text	Source string.
i	Current index (on the ESC byte). Updated in place.
result	Destination string. @utility

Version: 1.10.4

Definition at line 346 of file logging.cpp.

◆ escape_char()

bool entropic::log::escape_char	(	char	c,
		std::string &	result
	)

Append escaped form of c if special, else return false.

Parameters

c	Character to test.
result	Destination string.

Returns: True if c was escaped, false for passthrough. @utility

Version: 1.10.4

Definition at line 390 of file logging.cpp.

◆ escape_content()

std::string entropic::log::escape_content ( const std::string & text )

Escape content for safe spdlog formatting.

Replaces embedded newlines with \n, ANSI escape sequences with their hex representation, and curly braces (fmt specifiers) with doubled braces so spdlog/fmt does not interpret them.

Parameters

text	Raw content (user input or model output).

Returns: Escaped string safe for spdlog format strings. @utility

Version: 1.10.4

Replaces embedded newlines with \n, carriage returns with \r, ANSI escape sequences with [ESC...], and curly braces with doubled braces so spdlog/fmt does not interpret them as format specifiers.

Parameters

text	Raw content.

Returns: Escaped string safe for spdlog. @utility

Version: 1.10.4

Definition at line 409 of file logging.cpp.

◆ escape_table()

static const std::array< const char *, 256 > & entropic::log::escape_table ( )

static

256-entry table mapping bytes to escape strings (nullptr = passthrough).

Returns: Reference to static lookup table.

Definition at line 369 of file logging.cpp.

◆ get()

std::shared_ptr< spdlog::logger > entropic::log::get ( const std::string & name )

Get or create a named logger.

Get or create a named logger sharing current sinks.

Returns the existing logger if already created, or creates a new one sharing the root sink configuration.

Parameters

name	Logger name (e.g., "types", "inference", "mcp").

Returns: Shared pointer to the logger.

Example: auto log = entropic::log::get("inference");

log->info("Model loaded: {} ({:.1f} GB)", path, size_gb);

log->error("Load failed: {}", entropic_error_name(err));

entropic_error_name
ENTROPIC_EXPORT const char * entropic_error_name(entropic_error_t code)
Get the human-readable name for an error code.
Definition error.cpp:84

Version: 1.8.0

New loggers inherit sinks from the default logger rather than the original s_sink. This ensures loggers created after test infrastructure replaces sinks via spdlog::apply_all() still write to the correct destinations (e.g., per-test file sinks).

Parameters

name	Logger name.

Returns: Shared pointer to the logger.

Version: 2.3.7

Definition at line 211 of file logging.cpp.

◆ init()

void entropic::log::init ( spdlog::level::level_enum level = spdlog::level::info )

Initialize the logging subsystem.

Call once at engine startup (in entropic_create). Sets the global log level and output format. Subsequent calls are no-ops.

Parameters

level spdlog level (trace, debug, info, warn, error, critical).

Version: 1.8.0

Uses stderr so that engine diagnostic output does not interleave with the stdout streaming token callback used by TUI consumers.

Parameters

level spdlog level. Subsequent calls are no-ops. @utility

Version: 2.0.7

Definition at line 145 of file logging.cpp.

◆ log_content()

void entropic::log::log_content	(	const std::shared_ptr< spdlog::logger > &	logger,
		spdlog::level::level_enum	level,
		const std::string &	label,
		const std::string &	text
	)

Log full content with escaping applied.

Parameters

logger	Target logger.
level	spdlog level.
label	Prefix label (e.g., "Content", "Input").
text	Raw text — escaped before formatting. @utility

Version: 1.10.4

Parameters

logger	Target logger.
level	spdlog level.
label	Prefix label.
text	Raw text — escaped before formatting. @utility

Version: 1.10.4

Definition at line 431 of file logging.cpp.

◆ log_decision()

void entropic::log::log_decision	(	const std::shared_ptr< spdlog::logger > &	logger,
		const std::string &	label,
		const std::string &	key,
		const std::string &	value
	)

Log a decision/routing event.

Parameters

logger	Target logger.
label	Decision category (e.g., "Route", "Grammar").
key	Decision input.
value	Decision output. @utility

Version: 1.10.4

Parameters

logger	Target logger.
label	Decision category.
key	Decision input.
value	Decision output. @utility

Version: 1.10.4

Definition at line 484 of file logging.cpp.

◆ log_timing()

void entropic::log::log_timing	(	const std::shared_ptr< spdlog::logger > &	logger,
		const std::string &	label,
		double	ms
	)

Log a timing measurement.

Parameters

logger	Target logger.
label	Operation label.
ms	Elapsed milliseconds. @utility

Version: 1.10.4

Definition at line 448 of file logging.cpp.

◆ log_tokens()

void entropic::log::log_tokens	(	const std::shared_ptr< spdlog::logger > &	logger,
		int	count,
		double	time_ms
	)

Log token count with throughput.

Parameters

logger	Target logger.
count	Token count.
time_ms	Generation time in milliseconds. @utility

Version: 1.10.4

Definition at line 464 of file logging.cpp.

◆ register_handle_log()

void entropic::log::register_handle_log	(	int	handle_id,
		const std::filesystem::path &	log_dir
	)

gh#59 (v2.3.1): register a per-handle session.log file.

gh#59 public entry — see header.

Replaces the old global-mutation behavior of add_file_sink for the multi-handle case. Each handle registers its own log_dir under a unique handle_id. The process-wide HandleAwareSink consults the calling thread's current_handle_id (set via HandleLogScope) and writes only to that handle's file. No cross-handle bleed.

Idempotent: registering the same id twice replaces the old sink. Safe to call before or after init().

Parameters

handle_id	Monotonic handle identifier (engine_handle::log_id).
log_dir	Directory containing session.log + session_model.log.

Version: 2.3.1

@utility

Version: 2.3.1

Definition at line 500 of file logging.cpp.

◆ remove_console_sink()

static void entropic::log::remove_console_sink ( )

static

Set up session logging for a project directory.

Adds a spdlog file sink for session.log (captures all engine operational logging). Truncates session_model.log for a fresh session (raw streaming user/assistant content).

Parameters

log_dir Directory for session log files. @utility

Version: 2.0.1

Remove the console (stderr) sink from all loggers.

Called after adding a file sink to ensure logs go to exactly one destination. Matches by pointer identity against s_sink.

@utility

Version: 2.0.7

Definition at line 285 of file logging.cpp.

◆ set_console_enabled()

void entropic::log::set_console_enabled ( bool enabled )

Enable or disable the stderr console sink process-wide.

Enable/disable the stderr console sink process-wide.

When disabled, the shared stderr sink (s_sink) is stripped from the default logger and every registered logger, and a process-global flag makes get() filter it out of any logger created afterwards. Engine output then routes to the per-handle file sink only.

TUI consumers that paint to fd 2 (stderr) MUST disable this — an engine log line on fd 2 corrupts the painted screen. Default state (console enabled) is unchanged for operator/CLI consumers.

Parameters

enabled true to keep the console sink (default), false to remove it everywhere including future loggers.

Version: 2.3.7

Parameters

enabled false strips s_sink everywhere + flags get(). @utility

Version: 2.3.7

Definition at line 243 of file logging.cpp.

◆ setup_session()

void entropic::log::setup_session ( const std::filesystem::path & log_dir )

Set up session logging for a project directory.

Adds a spdlog file sink for session.log and truncates session_model.log for a fresh session. Centralizes log file lifecycle that was previously inline in the facade.

Parameters

log_dir Directory for session log files.

Version: 2.0.1

Adds a file sink for session.log, removes the console sink so logs go to exactly one destination. Truncates session_model.log.

Parameters

log_dir Directory for session log files. @utility

Version: 2.0.6

Definition at line 305 of file logging.cpp.

◆ unregister_handle_log()

void entropic::log::unregister_handle_log ( int handle_id )

gh#59 (v2.3.1): release a handle's session.log file sink.

gh#59 public entry — see header.

Called from entropic_destroy. Closes the underlying file sink. Safe to call on unregistered ids.

Parameters

handle_id Identifier previously passed to register_handle_log.

Version: 2.3.1

@utility

Version: 2.3.1

Definition at line 530 of file logging.cpp.

Variable Documentation

◆ s_console_disabled

std::atomic<bool> entropic::log::s_console_disabled {false}

static

Definition at line 126 of file logging.cpp.

◆ s_dispatcher

std::shared_ptr<HandleAwareSink> entropic::log::s_dispatcher

static

Definition at line 118 of file logging.cpp.

◆ s_init_flag

std::once_flag entropic::log::s_init_flag

static

Definition at line 22 of file logging.cpp.

◆ s_session_paths

std::unordered_set<std::string> entropic::log::s_session_paths

static

Definition at line 133 of file logging.cpp.

◆ s_session_paths_mu

std::mutex entropic::log::s_session_paths_mu

static

Definition at line 132 of file logging.cpp.

◆ s_sink

std::shared_ptr<spdlog::sinks::stderr_color_sink_mt> entropic::log::s_sink

static

Definition at line 23 of file logging.cpp.

◆ t_current_handle_id

thread_local int entropic::log::t_current_handle_id = 0

static

Thread-local current handle id (0 = no scope active).

Definition at line 36 of file logging.cpp.

Classes

Namespaces

Functions

Variables

Detailed Description

Function Documentation

◆ add_file_sink()

◆ current_handle_id()

◆ escape_ansi()

◆ escape_char()

◆ escape_content()

◆ escape_table()

◆ get()

◆ init()

◆ log_content()

◆ log_decision()

◆ log_timing()

◆ log_tokens()

◆ register_handle_log()

◆ remove_console_sink()

◆ set_console_enabled()

◆ setup_session()

◆ unregister_handle_log()

Variable Documentation

◆ s_console_disabled

◆ s_dispatcher

◆ s_init_flag

◆ s_session_paths

◆ s_session_paths_mu

◆ s_sink

◆ t_current_handle_id