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.

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.

• 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 logging context can be resolved when the decorated callable is invoked.

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.

Return type:

LogContextProto

Returns:

logging context used by the decorated operation.

Conceptually:

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

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.