LogContext

This page documents the object-level API for logger contexts.

A LogContext coordinates structured event logging for a namespace. It resolves logging infrastructure, applies event selection, normalizes payload data, creates LogEvent objects, and emits them through the effective sink.

Package-level functions such as configure_log_context() and get_log_context() are documented separately in the package-level API page.

Error handling policy

LogErrorHandlingPolicy defines how a context reacts when logging infrastructure fails while delivering a prepared event.

enum mvx.common.logger.LogErrorHandlingPolicy(value)

Policy for handling logging infrastructure failures inside LogContext.

This policy is applied when a prepared LogEvent cannot be delivered through the resolved sink.

Member Type:: str

Valid values are as follows:

IGNORE = <LogErrorHandlingPolicy.IGNORE: 'IGNORE'>: Suppress sink delivery errors.

PRINT_STDERR = <LogErrorHandlingPolicy.PRINT_STDERR: 'PRINT_STDERR'>: Report sink delivery errors through the last-resort stderr path.

RAISE = <LogErrorHandlingPolicy.RAISE: 'RAISE'>: Raise LogContextUnableToLog.

LogContext

LogContext is the main object-level API for structured logging.

A root context owns mandatory infrastructure: a sink and a payload processor. A child context can override selected components or inherit them from its parent.

class mvx.common.logger.LogContext(*, namespace: str | None = None, parent: None = None, log_sink: LogSinkProto, event_policy: LogEventPolicyProto | None = None, payload_processor: LogPayloadProcessorProto, log_error_handling_policy: LogErrorHandlingPolicy | None = None)

class mvx.common.logger.LogContext(*, namespace: str | None = None, parent: LogContext, log_sink: LogSinkProto | None = None, event_policy: LogEventPolicyProto | None = None, payload_processor: LogPayloadProcessorProto | None = None, log_error_handling_policy: LogErrorHandlingPolicy | None = None)

Structured logging context for a namespace.

LogContext is the object-level coordinator of the logger pipeline. It combines event metadata construction, event policy checks, payload normalization, and sink delivery.

A context may be used directly or through the package-level facade.

Create a root or child log context.

A root context has no parent and must receive both log_sink and payload_processor.

A child context has a parent and may define local overrides. Missing inherited components are resolved from the parent.

Parameters:

namespace (str | None) – optional context name.
parent (LogContext | None) – parent context, or None for a root context.
log_sink (LogSinkProto | None) – local sink. Required for a root context.
event_policy (LogEventPolicyProto | None) – optional local event policy.
payload_processor (LogPayloadProcessorProto | None) – local payload processor. Required for a root context.
log_error_handling_policy (LogErrorHandlingPolicy | None) – optional local policy for logging infrastructure failures. Root contexts default to PRINT_STDERR.

Raises:

TypeError – if an argument has an invalid type.
ValueError – if a root context is missing required infrastructure.

property namespace: str

Return the context namespace.

If no namespace was configured, returns "<not defined>".

Returns:: context namespace.

property is_root: bool

Return whether this context is the root context.

Returns:: True if the context has no parent, False otherwise.

property parent: LogContext | None

Return the parent context.

Returns:: parent context, or None for a root context.

property log_sink: LogSinkProto

Return the effective sink for this context.

If a local sink is configured, it is returned. Otherwise, the sink is resolved from the parent context.

Returns:: effective sink.

set_log_sink(log_sink)

Set the local sink for this context.

Parameters:

log_sink (LogSinkProto) – sink to assign locally.

Return type:

None

Returns:

None.

Raises:

ValueError – if log_sink is None.
TypeError – if log_sink does not implement LogSinkProto.

reset_log_sink()

Remove the local sink override.

After reset, a child context resolves its sink from the parent context.

Return type:: None
Returns:: None.
Raises:: LogContextResetError – if called on a root context.

property event_policy: LogEventPolicyProto | None

Return the local event policy.

Event policy is not inherited from the parent context. If no local policy is configured, returns None.

Returns:: local event policy, or None.

set_event_policy(event_policy)

Set the local event policy.

Parameters:

event_policy (LogEventPolicyProto) – event policy to assign locally.

Return type:

None

Returns:

None.

Raises:

ValueError – if event_policy is None.
TypeError – if event_policy does not implement LogEventPolicyProto.

reset_event_policy()

Remove the local event policy.

After reset, events emitted through this context are enabled by default.

Return type:: None
Returns:: None.

property payload_processor: LogPayloadProcessorProto

Return the effective payload processor.

If a local processor is configured, it is returned. Otherwise, the processor is resolved from the parent context.

Returns:: effective payload processor.

set_payload_processor(payload_processor)

Set the local payload processor.

Parameters:

payload_processor (LogPayloadProcessorProto) – payload processor to assign locally.

Return type:

None

Returns:

None.

Raises:

ValueError – if payload_processor is None.
TypeError – if payload_processor does not implement LogPayloadProcessorProto.

reset_payload_processor()

Remove the local payload processor override.

After reset, a child context resolves its payload processor from the parent context.

Return type:: None
Returns:: None.
Raises:: LogContextResetError – if called on a root context.

property log_error_handling_policy: LogErrorHandlingPolicy

Return the effective logging error handling policy.

If a local policy is configured, it is returned. Otherwise, the policy is resolved from the parent context.

Returns:: effective logging error handling policy.

set_log_error_handling_policy(log_error_handling_policy)

Set the local logging error handling policy.

Parameters:

log_error_handling_policy (LogErrorHandlingPolicy) – policy to assign locally.

Return type:

None

Returns:

None.

Raises:

ValueError – if log_error_handling_policy is None.
TypeError – if log_error_handling_policy is not a LogErrorHandlingPolicy.

reset_log_error_handling_policy()

Remove the local logging error handling policy override.

After reset, a child context resolves this policy from the parent context.

Return type:: None
Returns:: None.
Raises:: LogContextResetError – if called on a root context.

get_local_log_sink()

Return the locally configured sink.

This method does not resolve inherited sinks.

Return type:: LogSinkProto | None
Returns:: local sink, or None if no local sink is configured.

is_event_enabled(event)

Return whether an event is enabled for this context.

Only the local event policy is used. If no local event policy is configured, the event is enabled.

Parameters:: event (LogEventMeta) – event metadata to evaluate.
Return type:: bool
Returns:: True if the event is enabled, False otherwise.

emit_log_event(event)

Emit a fully prepared log event through the effective sink.

This method does not apply event policy and does not normalize payload data. The caller is responsible for providing a prepared LogEvent.

Sink delivery failures are handled according to the effective LogErrorHandlingPolicy.

Parameters:: event (LogEvent) – prepared event to emit.
Return type:: None
Returns:: None.
Raises:: LogContextUnableToLog – if sink delivery fails and the effective error handling policy is RAISE.

log_event(event, level, payload, *, event_namespace=None, event_outcome=None, entity_id=None, source_path=None, source_line=None, source_func=None, skip_payload_normalization=False)

Build and emit a structured log event.

The method builds LogEventMeta, checks the local event policy, normalizes the payload unless requested otherwise, creates LogEvent, and emits it through the effective sink.

Parameters:

event (str) – stable event name.
level (LogLevel) – event severity level.
payload (Mapping[str, Any]) – structured event payload.
event_namespace (str | None) – optional namespace override. If omitted, the context namespace is used.
event_outcome (str | None) – optional event outcome or phase.
entity_id (str | None) – optional related entity identifier.
source_path (str | None) – optional source file path.
source_line (int | None) – optional source line.
source_func (str | None) – optional source function name.
skip_payload_normalization (bool) – if True, use the payload as-is.

Return type:

None

Returns:

None.

Raises:

LogContextUnableToLog – if sink delivery fails and the effective error handling policy is RAISE.

log_debug_event(event, payload, *, event_namespace=None, event_outcome=None, entity_id=None, source_path=None, source_line=None, source_func=None, skip_payload_normalization=False)

Emit a structured debug-level event.

This is a convenience wrapper around log_event() with LogLevel.DEBUG.

Return type:

None

Returns:

None.

Parameters:

event (str)
payload (Mapping[str, Any])
event_namespace (str | None)
event_outcome (str | None)
entity_id (str | None)
source_path (str | None)
source_line (int | None)
source_func (str | None)
skip_payload_normalization (bool)

log_info_event(event, payload, *, event_namespace=None, event_outcome=None, entity_id=None, source_path=None, source_line=None, source_func=None, skip_payload_normalization=False)

Emit a structured info-level event.

This is a convenience wrapper around log_event() with LogLevel.INFO.

Return type:

None

Returns:

None.

Parameters:

event (str)
payload (Mapping[str, Any])
event_namespace (str | None)
event_outcome (str | None)
entity_id (str | None)
source_path (str | None)
source_line (int | None)
source_func (str | None)
skip_payload_normalization (bool)

log_warning_event(event, payload, *, event_namespace=None, event_outcome=None, entity_id=None, source_path=None, source_line=None, source_func=None, skip_payload_normalization=False)

Emit a structured warning-level event.

This is a convenience wrapper around log_event() with LogLevel.WARNING.

Return type:

None

Returns:

None.

Parameters:

event (str)
payload (Mapping[str, Any])
event_namespace (str | None)
event_outcome (str | None)
entity_id (str | None)
source_path (str | None)
source_line (int | None)
source_func (str | None)
skip_payload_normalization (bool)

log_error_event(event, payload, *, event_namespace=None, event_outcome=None, entity_id=None, source_path=None, source_line=None, source_func=None, skip_payload_normalization=False)

Emit a structured error-level event.

This is a convenience wrapper around log_event() with LogLevel.ERROR.

Return type:

None

Returns:

None.

Parameters:

event (str)
payload (Mapping[str, Any])
event_namespace (str | None)
event_outcome (str | None)
entity_id (str | None)
source_path (str | None)
source_line (int | None)
source_func (str | None)
skip_payload_normalization (bool)

build_error_payload(err)

Build a structured logging payload for an exception.

If the exception provides a callable to_log_payload() method returning a dictionary, that dictionary is used. Otherwise, the method builds a generic payload from available code, code_desc, exception kind, and message.

Parameters:: err (BaseException) – exception instance to describe.
Return type:: Mapping[str, Any]
Returns:: structured error payload.

is_error_logged(err)

Return whether the exception instance is marked as already logged.

This is a best-effort marker used to suppress repeated detailed error payloads for the same exception instance.

Parameters:: err (BaseException) – exception instance to check.
Return type:: bool
Returns:: True if the exception is marked as logged, False otherwise.

mark_error_logged(err)

Mark the exception instance as already logged.

The marker is best-effort. If the exception object does not allow setting custom attributes, the method silently does nothing.

Parameters:: err (BaseException) – exception instance to mark.
Return type:: None
Returns:: None.

normalize_payload(payload, *, unbounded=False)

Normalize a structured payload through the effective payload processor.

Parameters:

payload (Mapping[str, Any]) – payload mapping to normalize.
unbounded (bool) – whether item-count limiting should be disabled while normalizing this payload.

Return type:

dict[str, Any]

Returns:

normalized payload dictionary.

normalize_value_for_log(value, *, unbounded=False)

Normalize a single value through the effective payload processor.

Parameters:

value (Any) – value to normalize.
unbounded (bool) – whether item-count limiting should be disabled for this value.

Return type:

Returns:

normalized log-ready value.

get_plain_verbosity_level()

Return the effective payload processor verbosity level as a plain string.

Return type:: str | None
Returns:: Plain verbosity level, or None if no verbosity level is available.

Inheritance model

LogContext does not inherit all components in the same way.

log sink
    inherited

payload processor
    inherited

logging error handling policy
    inherited

event policy
    local only

A child context can reset local sink, payload processor, or error handling policy to return to inherited behavior.

The root context cannot reset sink, payload processor, or error handling policy because it has no parent fallback.

Event policy is local. Resetting it is always valid and means that events emitted through that context are enabled by default.

Manual event emission

The main manual logging method is log_event().

It performs the full context pipeline:

build LogEventMeta
   |
   v
check local event policy
   |
   v
normalize payload unless skipped
   |
   v
build LogEvent
   |
   v
emit through effective sink

Convenience methods call log_event() with predefined levels:

log_debug_event()    -> LogLevel.DEBUG
log_info_event()     -> LogLevel.INFO
log_warning_event()  -> LogLevel.WARNING
log_error_event()    -> LogLevel.ERROR

Prepared event emission

emit_log_event() is a lower-level method.

It expects a fully prepared LogEvent and sends it through the effective sink.

It does not apply event policy and does not normalize payload data.

Use it only when the caller has already built a log-ready event.

Error payload helpers

LogContext also exposes helper methods used by logging components such as log_invocation:

build_error_payload()
is_error_logged()
mark_error_logged()

These helpers make it possible to build structured error payloads and suppress repeated detailed error logging for the same exception instance.

Payload normalization helpers

LogContext delegates payload normalization to the effective payload processor:

normalize_payload()
normalize_value_for_log()
get_plain_verbosity_level()

These methods are useful for components that need to normalize selected values through the same rules as normal context logging.