Quick Reference

Cheat Sheet

Process Singleton Instantiation & Nesting

// Access or initialize process-wide singleton ScopeTrace instance
auto& log = siddiqsoft::ScopeTrace::CreateInstance("my_app", siddiqsoft::LogLevel::debug);

// Access process singleton without arguments
auto& root = siddiqsoft::ScopeTrace::CreateInstance();

// Update process threshold dynamically
root.set_level(siddiqsoft::LogLevel::trace);

// Nested scope creation (automatically formatted as "<parent_name>/<child_name>")
auto inner = root.nest("sub_task", siddiqsoft::LogLevel::info);

Structured Console Logging & Colors

// Trace log (dark blue output, active when threshold >= LogLevel::trace)
// RECOMMENDED FOR HIGH-VOLUME I/O: Socket reads/writes, packet dumps, buffer transfers
scope.trace("Socket read {} bytes from {}:{:d}", bytes, host, port);

// Debug log (light gray output, active when threshold >= LogLevel::debug, excludes trace)
scope.debug("Debugging state: count={}", count);

// Info log (default/neutral output, active when threshold >= LogLevel::info)
scope.info("Processing item {} of {}", current, total);

// Warning log (dark yellow/gold output, active when threshold >= LogLevel::warning)
scope.warn("Cache miss for key: {}", key);

// Error log (orange output, always logged regardless of threshold)
scope.err("Failed to open connection to host: {}", host);

// Unified Error & Throw shortcut (orange output, always logged)
scope.err_throw<std::runtime_error>("Fatal database connection timeout: {}s", timeout);

// Exception log shortcuts (always logged)
try {
    // ...
} catch (const std::exception& e) {
    // Basic exception log shortcut (logs typeid name and e.what())
    scope.exp(e);

    // Exception log shortcut with custom formatted context
    scope.exp(e, "Operation failed for request ID: {}", req_id);
}

Terminal Color Output Preview

Console Log Colors

2026-08-15T20:49:27.060564Z  [trace ] scope - Socket read 1024 bytes from 127.0.0.1:8080
2026-08-15T20:49:27.060600Z  [debug ] scope - Debugging state: count=42
2026-08-15T20:49:27.060620Z  [info  ] scope - Processing item 1 of 100
2026-08-15T20:49:27.060700Z  [warning] scope - Cache miss for key: user_123
2026-08-15T20:49:27.060800Z  [error  ] scope - Failed to open connection to host: db.internal
2026-08-15T20:49:27.060900Z  [exception] scope - std::runtime_error - Fatal database connection timeout: 5s - from:main.cpp@39
2026-08-15T20:49:27.061000Z  [exception] scope - std::exception - Device I/O error - Operation failed for request ID: REQ-99
2026-08-15T20:49:27.061100Z  [debug ] scope - COMPLETED: time:540us

Internal Scope Metrics & Helpers (Protected Methods)

// Protected implementation helpers (accessible in derived classes or when SCOPETRACE_PRIVATE_TESTING is defined):

// Elapsed duration since scope entry
auto duration = scope.elapsed();

// Instance nesting depth level
size_t level = scope.depth();

// Current thread nesting depth counter
size_t thread_depth = siddiqsoft::ScopeTrace::current_depth();

// ISO 8601 UTC timestamp string
std::string ts = siddiqsoft::ScopeTrace::current_timestamp();

// Extract plain function name matching __func__
std::string_view func = scope.function_name();