Skip to content

ScopeTrace

NuGet

siddiqsoft::ScopeTrace is a header-only C++23 RAII scope logger designed for execution tracing, performance measurement, and nesting depth visualization.

Motivation

How many of us have had to write code that is surrounded by #if defined(DEBUG).. and std::println(std::cerr, ..) through out your code.

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

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
}

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

void foo() {
    // Access process singleton with LogLevel::info threshold
    auto& root = siddiqsoft::ScopeTrace::CreateInstance("foo", siddiqsoft::LogLevel::info);

    try {
        auto inner = root.nest("Nested", siddiqsoft::LogLevel::info); // Inner scope label ("foo/Nested")

        inner.info("From the inner scope line: {}", __LINE__);
        // We log information and throw in one shot!
        inner.err_throw<std::runtime_error>("Deliberate error");
    }
    catch (const std::exception& e) {
        // Catch an error and log
        root.exp(e);
    }
}

Key Highlights

  • Zero-Boilerplate Tracing: Automatically record function name, file path, and line numbers using std::source_location and auto-extracted __func__ names.
  • 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()).
  • Structured Console Logging: Specialized logging methods for info(), trace(), warn(), err(), and exp() with depth indentation, ANSI colors, and ISO 8601 UTC timestamps.
  • C++23 Native Support: Leverages std::format and std::println to std::cerr.

Quick Example

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

void process_request()
{
    // Create nested scope from process singleton
    auto scope = siddiqsoft::ScopeTrace::CreateInstance().nest("process_request", siddiqsoft::LogLevel::info);
    scope.info("Parsing incoming payload...");
    scope.warn("Payload buffer usage: 82%");
    // Work executed here...
}

int main()
{
    // Access process singleton root
    auto& scope = siddiqsoft::ScopeTrace::CreateInstance("main", siddiqsoft::LogLevel::info);
    process_request();
    return 0;
}

Output & Coloring Preview

Console Output (std::cerr) 
  Creating NEW SCOPE main:0
  Creating NEW SCOPE process_request:0
2026-08-15T20:49:27.060564Z  [info  ]   process_request - Parsing incoming payload...
2026-08-15T20:49:27.060912Z  [warning]   process_request - Payload buffer usage: 82%
2026-08-15T20:49:27.061250Z  [debug ]   process_request - COMPLETED: time:688us
2026-08-15T20:49:27.061300Z  [debug ] main - COMPLETED: time:1240us