C++23 Stacktrace and Source Location: Debugging Like a Pro

Debugging complex C++ applications can be like finding a needle in a haystack. When a crash occurs deep in a library call, you often have no idea how you got there. C++23 introduces two powerful tools: std::stacktrace and std::source_location. These features bring stack trace and source location capabilities directly into the standard library, making debugging and logging more efficient and portable.

In this tutorial, you'll learn how to capture and analyze stack traces at runtime, and how to embed source location information into your logs and assertions. We'll cover practical examples, common pitfalls, and production-ready patterns. By the end, you'll be able to add robust debugging capabilities to your C++ applications with minimal overhead.

Whether you're maintaining a legacy codebase or building a new system, these tools will save you hours of debugging time. Let's dive in!

What is std::source_location?

std::source_location is a class that represents source location information (file name, line number, column number, and function name). It is obtained via the static method current(), which returns a source_location object populated with the call site's information. This is evaluated at compile time, so there is no runtime overhead when not used.

Example:

#include <source_location>
#include <iostream>

void log(const std::string& msg, const std::source_location& loc = std::source_location::current()) {
    std::cout << loc.file_name() << ":" << loc.line() << " " << loc.function_name() << " - " << msg << std::endl;
}

int main() {
    log("Hello, world!");
    return 0;
}

What is std::stacktrace?

std::stacktrace is a container of std::stacktrace_entry objects, each representing a frame in the call stack. You can capture the current stack trace with std::stacktrace::current(). The stacktrace can be printed or iterated. It is similar to boost::stacktrace but standard.

Example:

#include <stacktrace>
#include <iostream>

void func3() {
    auto st = std::stacktrace::current();
    std::cout << st << std::endl;
}

void func2() { func3(); }
void func1() { func2(); }

int main() {
    func1();
    return 0;
}

Using source_location in Logging Macros

One of the most practical uses of std::source_location is in logging macros. Instead of manually writing __FILE__ and __LINE__, you can define a macro that automatically passes the source location. This reduces boilerplate and ensures consistency.

Example:

#include <source_location>
#include <iostream>

#define LOG(msg) log(msg, std::source_location::current())

void log(const std::string& msg, const std::source_location& loc) {
    std::cout << "[" << loc.file_name() << ":" << loc.line() << "] " << msg << std::endl;
}

int main() {
    LOG("Starting process");
    // ...
    LOG("Process completed");
    return 0;
}

Capturing Stack Traces in Exception Handlers

When an exception is thrown, the stack is unwound. To capture the stack at the throw point, you need to capture it before the exception is caught. One common pattern is to capture the stack trace in the catch block, but that gives the catch site's stack, not the throw site's. To capture the throw site, you can use a custom exception class that stores a stack trace.

Example:

#include <stacktrace>
#include <iostream>
#include <stdexcept>

class traced_exception : public std::runtime_error {
public:
    traced_exception(const std::string& msg)
        : std::runtime_error(msg), trace_(std::stacktrace::current()) {}
    const std::stacktrace& trace() const { return trace_; }
private:
    std::stacktrace trace_;
};

void func() {
    throw traced_exception("Something went wrong");
}

int main() {
    try {
        func();
    } catch (const traced_exception& e) {
        std::cout << "Exception: " << e.what() << std::endl;
        std::cout << "Stack trace:\n" << e.trace() << std::endl;
    }
    return 0;
}

Comparing Stacktrace Entries

std::stacktrace_entry provides methods to get the source file, line number, and function name. You can compare entries for equality. This is useful for deduplication or filtering.

Example:

#include <stacktrace>
#include <iostream>

int main() {
    auto st1 = std::stacktrace::current();
    auto st2 = std::stacktrace::current();
    if (st1 == st2) {
        std::cout << "Same stack trace" << std::endl;
    } else {
        std::cout << "Different" << std::endl;
    }
    // Compare individual entries
    if (st1[0] == st2[0]) {
        std::cout << "Top frame same" << std::endl;
    }
    return 0;
}

Performance Considerations and Best Practices

Capturing a stack trace involves walking the stack and resolving symbols, which can be slow (microseconds to milliseconds). In production, you should: - Capture stack traces only on error paths. - Limit the depth using std::stacktrace::current(max_depth). - Use conditional compilation (e.g., #ifdef DEBUG) to disable stack tracing in release builds. - For source_location, there is no runtime cost when not used, but passing it by value copies the object (though it's small).

Example of conditional stack tracing:

#include <stacktrace>
#include <iostream>

void on_error() {
#ifdef DEBUG
    auto st = std::stacktrace::current(10); // limit to 10 frames
    std::cerr << "Error: stack trace:\n" << st << std::endl;
#else
    std::cerr << "Error occurred" << std::endl;
#endif
}

int main() {
    on_error();
    return 0;
}