ScopeTrace

siddiqsoft::ScopeTrace is a modern, lightweight, header-only C++23 RAII scope logger designed for performance profiling and scope execution tracing.

• RAII Scope Timing: Automatic duration measurement upon scope exit.
• std::source_location Integration: Capture file, line, and function automatically.
• Process Singleton Entry: Instantiated exclusively via static ScopeTrace::CreateInstance() process singleton.
• Nesting Level Tracking: Indents nested scope execution trees dynamically using parentage depth inheritance (nest()).
• Dynamic Log Level Filtering: Fine-grained threshold control (LogLevel / trace_level). Critical, exception, and error logs are always output, while warning, info, debug, and trace are filtered according to threshold (m_log_level).
• Structured Console Logging: Specialized info(), debug(), trace(), warn(), err(), err_throw(), and exp() methods for formatted console logging with ANSI colors and ISO 8601 UTC timestamps.

---

Documentation Site Links

For full detailed documentation, integration guides, and API specifications, visit our MkDocs documentation site:

• Features Overview
• Integration & CMake Guide
• Dependency Graph
• API Reference
• Examples & Walkthroughs

---

Quick Start

#include <iostream>
#include <siddiqsoft/ScopeTrace.hpp>

// Global instance configured with trace threshold
static siddiqsoft::ScopeTrace Log{"MYPROJECT", siddiqsoft::LogLevel::trace};

void sub_task()
{
    // Create nested context ("MYPROJECT-sub_task") with info threshold
    auto inner = Log.nest(__func__, siddiqsoft::LogLevel::info);
    auto last_line = __LINE__;

    try {
        last_line = __LINE__;
        inner.info("Processing items...");

        // Perform work...
        last_line = __LINE__;
        call_something(); // throws std::runtime_error("Device non-responsive")
    } catch (const std::exception& ex) {
        // Logs exception type, e.what(), and contextual line information
        inner.exp(ex, "Got exception last_line: {}", last_line);
    }

    // Upon scope exit, destructors log completed message and elapsed time
}

int main()
{
    Log.info("Starting application execution");
    sub_task();
    return 0;
}

---

Sample Output & Console Coloring

When running the quick start application, siddiqsoft::ScopeTrace outputs depth-indented log lines to std::cerr prefixed by ISO 8601 UTC timestamps and styled with ANSI level color codes:

Console Output (std::cerr)

  Creating NEW SCOPE MYPROJECT:6
2026-08-15T20:49:27.060564Z  [info  ] MYPROJECT - Starting application execution
  Creating NEW SCOPE MYPROJECT/sub_task:4
2026-08-15T20:49:27.060600Z  [info  ]   MYPROJECT/sub_task - Processing items...
2026-08-15T20:49:27.061200Z  [except]   MYPROJECT/sub_task - std::runtime_error - Device non-responsive - Got exception last_line: 54
2026-08-15T20:49:27.061250Z  [debug ]   MYPROJECT/sub_task - COMPLETED: time:650us
2026-08-15T20:49:27.061300Z  [debug ] MYPROJECT - COMPLETED: time:7360us

Log Level Color Palette

Log Level / Method	Tag Label	Color Output	ANSI Code	Visual Output Preview
trace_level::critical	[crit ]	Red	\033[0;31m	[crit ] System memory exhaustion
trace_level::exception	[except]	Red	\033[0;31m	[except] std::runtime_error - Connection refused
trace_level::error	[error ]	Orange	\033[38;5;208m	[error ] Failed to open configuration file
trace_level::warning	[warn ]	Dark Yellow	\033[38;5;136m	[warn ] Cache capacity reached 92%
trace_level::info	[info ]	Default / Neutral	\033[0m	[info ] Server listening on port 8080
trace_level::debug	[debug ]	Light Gray	\033[38;5;250m	[debug ] Worker thread depth: 2
trace_level::trace	[trace ]	Dark Blue	\033[38;5;19m	[trace ] RX payload: 0x41 0x42 0x43
Scope Exit	COMPLETED	Green Time	\033[0;32m	COMPLETED: time:450us

---

Installation & Integration

Integrate via CPM.cmake:

include(CPM.cmake)

CPMAddPackage("gh:SiddiqSoft/ScopeTrace#v1.0.0")

target_link_libraries(your_target PRIVATE siddiqsoft::ScopeTrace)

For more details, see the CMake & Integration Documentation.

---

Requirements & Building

• C++ Compiler: C++23 compliant compiler (MSVC 2022 v17.10+, GCC 13+, Clang 17+).
• CMake: Version >= 3.29.

Preset Build & Test

# Configure using Apple-Debug / Linux-GCC-Debug / Windows-x64-Debug preset
cmake --preset Darwin

# Build test binaries
cmake --build build/Darwin

# Execute unit tests
ctest --test-dir build/Darwin

---

License

Distributed under the BSD 3-Clause License. Copyright (c) 2026 Siddiq Software LLC.