File sink

This page documents the ready-to-use file sink.

FileLogSink delivers structured logger events to a file through Python’s standard logging package. It is built on top of AsyncioLogSink, so public log() calls enqueue events while actual file delivery is handled by the sink runtime.

Use this sink when you want log events written to a file without implementing a custom sink.

Overview

The file sink stack has two main public pieces:

LoggingFileConfig
    configures the standard-library file handler

FileLogSink
    delivers LogEvent records to the configured file

FileLogSink adapts LogEvent objects to standard-library logging.LogRecord objects and passes them to an internal logging.Logger configured with a file handler.

File configuration

LoggingFileConfig configures the handler used by FileLogSink.

It controls the target file path, minimum level, file mode, encoding, formatting, date formatting, formatter factory, and handler filters.

class mvx.common.logger.LoggingFileConfig(file_path, level=LogLevel.INFO, *, mode='a', encoding='utf-8', log_format='%(asctime)s %(levelname)s: %(message)s %(payload)s', date_format='%Y-%m-%d %H:%M:%S', formatter_factory=None, filters=None)

Configuration for a logger-backed file sink.

The configuration creates a logging.FileHandler for the configured file path.

Create a file sink configuration.

Parameters:

  • file_path (str | PathLike[str]) – path to the log file.

  • level (LogLevel) – minimum log level accepted by the logger and handler.

  • mode (str) – file opening mode passed to logging.FileHandler.

  • encoding (str) – file encoding passed to logging.FileHandler.

  • log_format (str) – format string passed to logging.Formatter.

  • date_format (str) – date/time format passed to logging.Formatter.

  • formatter_factory (Optional[Callable[[str, str], Formatter]]) – optional factory used to create a custom formatter.

  • filters (tuple[Union[Filter, Callable[[LogRecord], bool]], ...] | None) – optional tuple of logging filters or filter callables attached to the created handler.

Raises:

TypeError – if an argument has an invalid type.

property file_path: str | PathLike[str]

Return the configured log file path.

Returns:

log file path.

property mode: str

Return the configured file opening mode.

Returns:

file opening mode.

property encoding: str

Return the configured file encoding.

Returns:

file encoding.

File sink

FileLogSink is the ready-to-use sink implementation.

It owns an internal standard-library logger and installs a file handler configured by LoggingFileConfig.

class mvx.common.logger.FileLogSink(*, logger_name='mvx.file_log_sink', config, **kwargs)

Ready-to-use asynchronous sink for file output.

FileLogSink owns an internal logging.Logger configured by LoggingFileConfig. It delivers prepared LogEvent objects to the configured file through the AsyncioLogSink runtime.

Create a file sink.

Parameters:

  • logger_name (str) – name assigned to the internal standard-library logger.

  • config (LoggingFileConfig) – file logging configuration used to create the file handler.

  • kwargs (Any) – additional keyword arguments passed to AsyncioLogSink.

Raises:

  • TypeError – if an argument has an invalid type.

  • ValueError – if logger_name or config is None, or if logger_name is empty.

classmethod build_descriptor(**kwargs)

Build a descriptor for a file sink configuration.

The descriptor is used by the package-level sink registry to detect idempotent configuration requests and conflicts. The file path is expanded and resolved before it is stored in the descriptor resource key.

Parameters:

kwargs (Any) – file sink construction arguments.

Return type:

LogSinkDescriptor

Returns:

file sink descriptor.

Raises:

  • TypeError – if an argument has an invalid type.

  • ValueError – if logger_name is None or empty.

classmethod create(**kwargs)

Create a file sink and its terminator.

The terminator stops the asynchronous sink runtime and closes the file handler. The file handler is closed even if the sink was created but never started.

Parameters:

kwargs (Any) – arguments passed to FileLogSink.

Return type:

tuple[LogSinkProto, Callable[[], None]]

Returns:

pair containing the created sink and an idempotent terminator.

Raises:

TypeError – if the created sink is not a FileLogSink instance.

FileLogSink inherits the public runtime methods from AsyncioLogSink, including event acceptance and lifecycle operations. The detailed async sink runtime API is documented separately.

Package-level registration

A file sink can be registered through the package-level facade.

from mvx.common.logger import (
    FileLogSink,
    LoggingFileConfig,
    configure_log_sink,
)

config = LoggingFileConfig(
    file_path="app.log",
)

sink = configure_log_sink(
    name="file",
    sink_cls=FileLogSink,
    config=config,
)

The configured sink can then be assigned to a context through the package-level context facade or passed directly to a LogContext.

Custom file configuration

Use LoggingFileConfig to control file handler settings.

from mvx.common.logger import (
    FileLogSink,
    LogLevel,
    LoggingFileConfig,
    configure_log_sink,
)

config = LoggingFileConfig(
    file_path="logs/app.log",
    level=LogLevel.INFO,
    mode="a",
    encoding="utf-8",
)

sink = configure_log_sink(
    name="app_file",
    sink_cls=FileLogSink,
    config=config,
)

The file path is passed to Python’s standard logging.FileHandler.

Handler behavior

LoggingFileConfig creates a standard-library logging.FileHandler.

When applied to the internal logger, the configuration:

creates the file handler
sets the formatter
adds configured filters
sets logger and handler levels
removes existing handlers
turns off propagation
attaches the new handler

Existing file handlers are closed when replaced. Existing non-file handlers are detached but not closed.

Asynchronous delivery

FileLogSink uses AsyncioLogSink as its delivery runtime.

That means the sink is used through the normal sink boundary, but actual file delivery is performed by the async sink dispatcher.

At a high level:

LogContext emits LogEvent
   |
   v
FileLogSink.log(event)
   |
   v
event is accepted by AsyncioLogSink runtime
   |
   v
_dispatch_core(event) writes through the file logger

The ready-to-use file sink page does not document every async runtime method. For lifecycle states, wait handles, queue overflow behavior, and custom async sink implementation details, see the AsyncioLogSink component page.

Descriptor behavior

FileLogSink.build_descriptor() builds a descriptor used by the package-level sink registry.

For file sinks, the descriptor identity includes:

sink type
resolved file path
logger name
level
format settings
file mode
encoding
filter types

The file path is expanded and resolved before it is stored in the descriptor resource key.

This descriptor lets repeated configure_log_sink() calls be idempotent when the configuration is the same and conflicting when the same name is reused for a different file sink configuration.

Closing behavior

The terminator returned by FileLogSink.create() stops the async sink runtime and closes the installed file handler.

The file handler is closed even if the sink was created but never started.

Handler closing is idempotent.