RAII guard for automatic context management. More...

#include <scoped_context_guard.h>

Collaboration diagram for kcenon::logger::scoped_context_guard:

Public Member Functions
	scoped_context_guard (logger &log)
	Construct guard and save current context.

	scoped_context_guard (logger &log, std::string_view key, context_value value, context_category category=context_category::custom)
	Construct guard and set a single context field.

	~scoped_context_guard ()
	Destructor - restores previous context.

	scoped_context_guard (const scoped_context_guard &)=delete

scoped_context_guard &	operator= (const scoped_context_guard &)=delete

	scoped_context_guard (scoped_context_guard &&other) noexcept

scoped_context_guard &	operator= (scoped_context_guard &&other) noexcept

scoped_context_guard &	set (std::string_view key, context_value value, context_category category=context_category::custom)
	Set a context value.

scoped_context_guard &	set_trace (std::string_view trace_id, std::string_view span_id, std::optional< std::string_view > parent_span_id=std::nullopt)
	Set trace context.

scoped_context_guard &	set_request (std::string_view request_id, std::optional< std::string_view > correlation_id=std::nullopt)
	Set request context.

scoped_context_guard &	set_otel (const otlp::otel_context &ctx)
	Set OpenTelemetry context.

Private Member Functions
void	track_key (std::string_view key)
	Track a key as added or overridden.

Private Attributes
logger *	logger_

unified_log_context	saved_context_

std::vector< std::string >	tracked_keys_

Detailed Description

RAII guard for automatic context management.

Provides exception-safe context management by saving the current context state on construction and restoring it on destruction. Supports chainable setters for convenient context configuration.

The guard tracks which keys were added during its lifetime and removes only those keys on destruction, while restoring any values that were overridden.

Thread Safety: Each instance is tied to a specific logger instance and should only be used from a single thread. However, multiple threads can use separate guards with the same logger safely.

Definition at line 101 of file scoped_context_guard.h.

Constructor & Destructor Documentation

◆ scoped_context_guard() [1/4]

kcenon::logger::scoped_context_guard::scoped_context_guard ( logger & log )

explicit

Construct guard and save current context.

Parameters

log	Logger whose context to manage

Saves the current state of the logger's context. On destruction, the context will be restored to this state.

Definition at line 12 of file scoped_context_guard.cpp.

    : logger_(&log), saved_context_(log.context()) {
    // Save current context state for restoration
}

◆ scoped_context_guard() [2/4]

kcenon::logger::scoped_context_guard::scoped_context_guard	(	logger &	log,
		std::string_view	key,
		context_value	value,
		context_category	category = context_category::custom )

Construct guard and set a single context field.

Parameters

log	Logger whose context to manage
key	Field name to set
value	Field value to set
category	Context category (default: custom)

Convenience constructor for setting a single field. Equivalent to constructing with logger and then calling set().

Definition at line 17 of file scoped_context_guard.cpp.

    : scoped_context_guard(log) {
    set(key, value, category);
}

References set().

Here is the call graph for this function:

◆ ~scoped_context_guard()

kcenon::logger::scoped_context_guard::~scoped_context_guard ( )

Destructor - restores previous context.

Removes all keys that were added by this guard and restores any values that were overridden. This ensures the logger's context is returned to its state before the guard was constructed.

Definition at line 25 of file scoped_context_guard.cpp.

                                            {
    if (!logger_) {
        return; // Moved-from state
    }
 
    // Get current context
    auto& ctx = logger_->context();
 
    // Remove all tracked keys from current context
    for (const auto& key : tracked_keys_) {
        ctx.remove(key);
    }
 
    // Restore values from saved context
    for (const auto& key : saved_context_.keys()) {
        auto value = saved_context_.get(key);
        auto category = saved_context_.get_category(key);
        if (value && category) {
            ctx.set(key, *value, *category);
        }
    }
}

References kcenon::logger::logger::context(), kcenon::logger::unified_log_context::get(), kcenon::logger::unified_log_context::get_category(), kcenon::logger::unified_log_context::keys(), logger_, saved_context_, and tracked_keys_.

Here is the call graph for this function:

◆ scoped_context_guard() [3/4]

kcenon::logger::scoped_context_guard::scoped_context_guard ( const scoped_context_guard & )

delete

◆ scoped_context_guard() [4/4]

kcenon::logger::scoped_context_guard::scoped_context_guard ( scoped_context_guard && other )

noexcept

Definition at line 48 of file scoped_context_guard.cpp.

    : logger_(other.logger_),
      saved_context_(std::move(other.saved_context_)),
      tracked_keys_(std::move(other.tracked_keys_)) {
    other.logger_ = nullptr; // Mark other as moved-from
}

Member Function Documentation

◆ operator=() [1/2]

scoped_context_guard & kcenon::logger::scoped_context_guard::operator= ( const scoped_context_guard & )

delete

◆ operator=() [2/2]

scoped_context_guard & kcenon::logger::scoped_context_guard::operator= ( scoped_context_guard && other )

noexcept

Definition at line 55 of file scoped_context_guard.cpp.

                                                                                           {
    if (this != &other) {
        // First, restore our current state (like destructor)
        if (logger_) {
            auto& ctx = logger_->context();
            for (const auto& key : tracked_keys_) {
                ctx.remove(key);
            }
            for (const auto& key : saved_context_.keys()) {
                auto value = saved_context_.get(key);
                auto category = saved_context_.get_category(key);
                if (value && category) {
                    ctx.set(key, *value, *category);
                }
            }
        }
 
        // Transfer ownership from other
        logger_ = other.logger_;
        saved_context_ = std::move(other.saved_context_);
        tracked_keys_ = std::move(other.tracked_keys_);
        other.logger_ = nullptr;
    }
    return *this;
}

◆ set()

scoped_context_guard & kcenon::logger::scoped_context_guard::set	(	std::string_view	key,
		context_value	value,
		context_category	category = context_category::custom )

Set a context value.

Parameters

key	Field name
value	Field value
category	Context category (default: custom)

Returns: Reference to this guard for chaining

Sets a key-value pair in the logger's context. If the key already exists, its value is overridden and the previous value is saved for restoration.

Definition at line 81 of file scoped_context_guard.cpp.

                                                                           {
    if (logger_) {
        logger_->context().set(key, value, category);
        track_key(key);
    }
    return *this;
}

References kcenon::logger::logger::context(), logger_, kcenon::logger::unified_log_context::set(), and track_key().

Referenced by scoped_context_guard().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set_otel()

scoped_context_guard & kcenon::logger::scoped_context_guard::set_otel ( const otlp::otel_context & ctx )

Set OpenTelemetry context.

Parameters

ctx	OpenTelemetry context structure

Returns: Reference to this guard for chaining

Imports all fields from an otel_context structure with context_category::otel.

Definition at line 119 of file scoped_context_guard.cpp.

                                                                                {
    if (logger_) {
        logger_->context().set_otel(ctx);
        // Track all OTEL context keys
        if (!ctx.trace_id.empty()) {
            track_key("otel_trace_id");
        }
        if (!ctx.span_id.empty()) {
            track_key("otel_span_id");
        }
        if (!ctx.trace_flags.empty()) {
            track_key("otel_trace_flags");
        }
        if (!ctx.trace_state.empty()) {
            track_key("otel_trace_state");
        }
    }
    return *this;
}

References kcenon::logger::logger::context(), logger_, kcenon::logger::unified_log_context::set_otel(), kcenon::logger::otlp::otel_context::span_id, kcenon::logger::otlp::otel_context::trace_flags, kcenon::logger::otlp::otel_context::trace_id, kcenon::logger::otlp::otel_context::trace_state, and track_key().

Here is the call graph for this function:

◆ set_request()

scoped_context_guard & kcenon::logger::scoped_context_guard::set_request	(	std::string_view	request_id,
		std::optional< std::string_view >	correlation_id = std::nullopt )

Set request context.

Parameters

request_id	Request identifier
correlation_id	Optional correlation identifier

Returns: Reference to this guard for chaining

Convenience method for setting request tracking context. Sets request_id and optionally correlation_id with context_category::request.

Definition at line 106 of file scoped_context_guard.cpp.

                                                {
    if (logger_) {
        logger_->context().set_request(request_id, correlation_id);
        track_key("request_id");
        if (correlation_id) {
            track_key("correlation_id");
        }
    }
    return *this;
}

References kcenon::logger::logger::context(), logger_, kcenon::logger::unified_log_context::set_request(), and track_key().

Here is the call graph for this function:

◆ set_trace()

scoped_context_guard & kcenon::logger::scoped_context_guard::set_trace	(	std::string_view	trace_id,
		std::string_view	span_id,
		std::optional< std::string_view >	parent_span_id = std::nullopt )

Set trace context.

Parameters

trace_id	Trace identifier
span_id	Span identifier
parent_span_id	Optional parent span identifier

Returns: Reference to this guard for chaining

Convenience method for setting distributed tracing context. Sets trace_id, span_id, and optionally parent_span_id with context_category::trace.

Definition at line 91 of file scoped_context_guard.cpp.

                                                {
    if (logger_) {
        logger_->context().set_trace(trace_id, span_id, parent_span_id);
        track_key("trace_id");
        track_key("span_id");
        if (parent_span_id) {
            track_key("parent_span_id");
        }
    }
    return *this;
}

References kcenon::logger::logger::context(), logger_, kcenon::logger::unified_log_context::set_trace(), and track_key().

Here is the call graph for this function:

◆ track_key()

void kcenon::logger::scoped_context_guard::track_key ( std::string_view key )

private

Track a key as added or overridden.

Parameters

key	Key that was set

Definition at line 139 of file scoped_context_guard.cpp.

                                                       {
    std::string key_str(key);
    // Only add if not already tracked (avoid duplicates)
    if (std::find(tracked_keys_.begin(), tracked_keys_.end(), key_str) == tracked_keys_.end()) {
        tracked_keys_.push_back(std::move(key_str));
    }
}