API

This page documents the public API of the log_invocation component.

log_invocation exposes one primary public function and several integration protocols used by that function.

The function is the decorator factory:

from mvx.common.logger import log_invocation

The protocols describe the context-like objects that log_invocation can work with:

from mvx.common.logger import (
    LogContextProto,
    LogContextProviderProto,
    LogEntityIdProviderProto,
)

Decorator factory

log_invocation is a decorator factory.

It creates a decorator that wraps a public API operation and emits structured lifecycle outcomes through a resolved logging context.

The decorated operation is treated as one event. The operation lifecycle is represented through event_outcome values such as invoke, success, failed, and cancelled.

mvx.common.logger.log_invocation(event, *, invoke_level=LogLevel.DEBUG, success_level=LogLevel.DEBUG, error_level=LogLevel.ERROR, error_level_suppressed=LogLevel.DEBUG, cancel_level=LogLevel.INFO, log_closures_on_invoke=None, context_fields=(), context_formatter=None, log_kwargs_on_invoke=(), log_result_on_success=None, log_error_policy=(), ctx=None, entity_id_getter=None)

Decorate a public API operation with structured lifecycle logging.

The decorated callable is treated as one event. The decorator may emit log records for that event with different outcomes:

• invoke before the operation body starts;

• success after successful completion;

• failed when the operation raises an ordinary exception;

• cancelled when the operation raises asyncio.CancelledError.

The decorator does not create or configure a logging context. It either uses the explicit ctx argument or resolves a context from the first positional argument through LogContextProviderProto.

If the context provider returns None, decorator-driven logging is disabled for the current call. The decorated callable is executed normally and no invoke, success, failed, or cancelled lifecycle events are emitted by this decorator.

The original return value, exception, and cancellation semantics are preserved.

Parameters:

• event (str) – event name for the decorated operation. Must match ^[A-Za-z_.]+$.

• invoke_level (LogLevel) – level used for the invoke outcome.

• success_level (LogLevel) – level used for the success outcome.

• error_level (LogLevel) – level used for a full failed outcome.

• error_level_suppressed (LogLevel) – level used for a suppressed failed outcome.

• cancel_level (LogLevel) – level used for the cancelled outcome.

• log_closures_on_invoke (dict[str, Any] | None) – values captured from the surrounding scope and added to the invoke payload under the closures key.

• context_fields (tuple[str, ...]) – field specifications resolved for every emitted outcome.

• context_formatter (Optional[Callable[[LogContextProto, str, str, dict[str, Any]], dict[str, Any]]]) – optional formatter that can shape payload data produced from context_fields.

• log_kwargs_on_invoke (tuple[str, ...]) – field specifications resolved only for the invoke outcome and added under the kwargs payload key.

• log_result_on_success (tuple[str, ...] | None) – result logging configuration. None disables result logging, an empty tuple logs the whole result, and a non-empty tuple selects result fields.

• log_error_policy (tuple[tuple[type[BaseException], bool], ...]) – rules controlling whether matching exception types produce a full or suppressed failed outcome.

• ctx (LogContextProto | None) – explicit logging context. If omitted, the decorator resolves the context from the first positional argument. If that argument provides LogContextProviderProto and returns None, decorator-driven logging is disabled for the current call.

• entity_id_getter (Optional[Callable[[], str]]) – optional zero-argument callable used to provide LogEventMeta.entity_id. If omitted, the decorator tries to resolve an identity from the first positional argument.

Return type:

Callable[[TypeVar(F, bound= Callable[..., Any])], TypeVar(F, bound= Callable[..., Any])]

Returns:

a decorator that wraps the target callable.

Raises:

• ValueError – if event has an invalid name.

• RuntimeError – if no explicit context is provided and no context provider can be found on the first positional argument. A provider returning None is treated as an explicit request to disable decorator-driven logging, not as a resolution failure.

Integration protocols

log_invocation does not require the concrete LogContext class.

Instead, it works with a context-like object that satisfies LogContextProto.

This allows the decorator to be used with LogContext itself or with another object that exposes the minimal behavior required by the decorator.

class mvx.common.logger.LogContextProto(*args, **kwargs)

is_event_enabled(event)

Return whether the event described by the given metadata is enabled.

log_invocation calls this method before emitting normal operation tracing outcomes such as invoke and success.

Parameters:

event (LogEventMeta) – event metadata to check.

Return type:

bool

Returns:

True if the event is enabled, False otherwise.

get_plain_verbosity_level()

Return the current verbosity level as a plain string.

log_invocation uses this value to evaluate verbosity-gated field specifications such as MAXIMUM:payload or NORMAL,MAXIMUM:request_id.

Return type:

str | None

Returns:

the current plain verbosity level, or None if no level is set.

property namespace: str

Return the namespace used for events emitted through this context.

log_invocation copies this value into LogEventMeta.event_namespace when building metadata for the decorated operation.

Returns:

the context namespace.

normalize_value_for_log(value, *, unbounded=False)

Normalize a single value for inclusion in a log payload.

log_invocation uses this method for selected argument values, context fields, closure values, and selected result values.

Parameters:

• value (Any) – value to normalize.

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

Return type:

str | int | float | bool | bytes | dict[str, Any] | list[Any] | None

Returns:

the normalized log-ready value.

build_error_payload(err)

Build a structured payload for an exception.

log_invocation uses this method for full failed outcomes and for emitted cancelled outcomes.

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 already marked as logged.

log_invocation uses this marker 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 already marked as logged.

mark_error_logged(err)

Mark the exception instance as already logged.

log_invocation calls this after emitting a full error payload or after applying an explicit error policy rule.

Parameters:

err (BaseException) – exception instance to mark.

Return type:

None

Returns:

None.

emit_log_event(event)

Emit a fully prepared log event.

This method is the final boundary used by log_invocation. The event metadata, outcome, timestamp, level, and payload have already been prepared by the caller.

This method does not apply event selection for log_invocation and does not build the operation payload.

Parameters:

event (LogEvent) – prepared log event to emit.

Return type:

None

Returns:

None.

Method-based context resolution

For method-based usage, log_invocation can resolve the logging context from the first positional argument.

For instance methods, that argument is usually self.

The object must satisfy LogContextProviderProto:

class mvx.common.logger.LogContextProviderProto(*args, **kwargs)

get_log_context()

Return the logging context for this object.

log_invocation uses this protocol for method-based context resolution. For instance methods, the first positional argument is usually self, and this method supplies the effective context.

Returning None explicitly disables logging through log_invocation for the current call. In that case, the decorated callable is executed normally and no invocation lifecycle events are emitted.

Return type:

LogContextProto | None

Returns:

logging context used by the decorated operation, or None to disable decorator-driven logging for the current call.

Conceptually:

self -> get_log_context() -> LogContextProto-compatible object | None

If get_log_context() returns None, decorator-driven logging is disabled for the current call.

If the decorator receives an explicit ctx argument, this protocol is not used for context resolution.

Method-based entity id resolution

log_invocation can also resolve an optional entity id from the first positional argument.

The object must satisfy LogEntityIdProviderProto:

class mvx.common.logger.LogEntityIdProviderProto(*args, **kwargs)

property identity: str

Return the stable entity identifier for this object.

log_invocation uses this value as LogEventMeta.entity_id when no explicit entity_id_getter is supplied.

Returns:

entity identifier.

Conceptually:

self -> identity -> LogEventMeta.entity_id

If the decorator receives an explicit entity_id_getter, that getter is used instead.

Related logger APIs

log_invocation uses common logger types such as LogLevel, LogEventMeta, and LogEvent.

Those types are documented in the main logger API reference, not on this page.