SiddiqSoft.ScopeTrace 0.10.0

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.
• Nesting Level Tracking: Indents nested scope execution trees dynamically using thread-local depth counter (current_depth()) and nest() method.
• Structured Console Logging: Specialized info(), trace(), warn(), err(), and exp() methods for formatted console logging with ANSI colors and ISO 8601 UTC timestamps.
• String Formatting & Stream Support: Native to_string() formatting and operator<< stream insertion support.

Motivation

How many of us have had to write

=== "Before: Using macros.."

You had to add guards and litter your code with macros..

```cpp
void foo() {
#if defined(DEBUG)
        std::println(std::cerr, "{} - Something or the other", __func__);
#endif

    try {
        ...
    } catch(std::exception& e) {
        std::println(std::cerr, "{} - Exception: {}", __func__, e.what());
    }

#if defined(DEBUG)
        std::println(std::cerr, "{} - COMPLETED", __func__);
#endif
}
```

=== "With ScopeTrace.."

Focus on your code and write your message/comments without worrying about formatting strings, colors, indentation and calculating the timings..

```cpp
void foo() {
    siddiqsoft::ScopeTrace scope; // automatically defaults scope name to plain __func__ ("foo")

    try {
        auto inner = scope.nest("Nested"); // explicit inner scope label ("foo-Nested")

        inner.info("From the inner scope line: {}", __LINE__);
        throw std::runtime_error(std::format("Deliberate error from line: {}", __LINE__));
    }
    catch (const std::exception& e) {
        scope.exp(e);
    }
}
```

=== "ScopeTrace output in `DEBUG` mode"

    Note the ISO 8601 UTC timestamp, nesting, and color output
    ```
    2026-08-13T23:16:00.519049Z    foo-Nested - From the inner scope line: 56
    2026-08-13T23:16:00.519100Z    foo-Nested - COMPLETED - time:71us
    2026-08-13T23:16:00.519120Z  foo - St13runtime_error - Deliberate error from line: 57
    2026-08-13T23:16:00.519150Z  foo - COMPLETED - time:138us
    ```

=== "ScopeTrace output in `RELEASE` mode"

    ```
    2026-08-13T23:16:00.519120Z  foo - St13runtime_error - Deliberate error from line: 57
    ```

📚 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>

void sub_task()
{
    siddiqsoft::ScopeTrace inner;
    inner.info("Processing items...");
    // Perform work...
}

int main()
{
    siddiqsoft::ScopeTrace scope;

    scope.info("Starting application execution");

    try {
        sub_task();
    }
    catch (const std::exception& e) {
        scope.exp(e);
    }

    return 0;
}

🔍 Function Name Extraction (__func__)

ScopeTrace provides built-in utilities to extract the clean function name matching __func__ from verbose std::source_location::function_name() signatures:

void MyClass::process_data()
{
    siddiqsoft::ScopeTrace scope;

    // Returns "process_data"
    std::string_view name1 = scope.function_name();
    std::string_view name2 = scope.func_name(); // Alias

    // Static helper for any signature string
    std::string_view name3 = siddiqsoft::ScopeTrace::extract_func_name("virtual void MyClass::process_data(int) const");
}

// When declared in global scope (outside of any function):
static siddiqsoft::ScopeTrace g_scope; // Scope name defaults to "GLOBAL"

📦 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.