Stream sink

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

StreamLogSink delivers structured logger events to a standard stream through Python’s standard logging package. It is the default lightweight sink for console-style output.

Use this sink when you want log events written to stdout or stderr without building a custom sink.

Overview

The stream sink stack has three public pieces:

LogStreamOutput
    selects stdout or stderr

LoggingStreamConfig
    configures the standard-library logging handler

StreamLogSink
    delivers LogEvent records to the configured stream

StreamLogSink adapts LogEvent objects to standard-library logging.LogRecord objects and passes them to an internal logging.Logger.

Stream target

LogStreamOutput defines supported standard stream targets.

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

Standard stream targets supported by LoggingStreamConfig.

Member Type:: str

Valid values are as follows:

STDOUT = <LogStreamOutput.STDOUT: 'stdout'>: Standard output stream.

STDERR = <LogStreamOutput.STDERR: 'stderr'>: Standard error stream.

Stream configuration

LoggingStreamConfig configures the handler used by StreamLogSink.

It controls the stream target, minimum level, formatting, date formatting, formatter factory, and handler filters.

class mvx.common.logger.LoggingStreamConfig(stream_output=LogStreamOutput.STDERR, level=LogLevel.INFO, *, 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 stream sink.

The configuration creates a logging.StreamHandler targeting stdout or stderr.

Create a stream sink configuration.

Parameters:

stream_output (LogStreamOutput) – standard stream target used by the created handler.
level (LogLevel) – minimum log level accepted by the logger and handler.
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 stream_output: LogStreamOutput

Return the configured stream target.

Returns:: standard stream target.

Stream sink

StreamLogSink is the ready-to-use sink implementation.

It owns an internal standard-library logger and installs a stream handler configured by LoggingStreamConfig.

class mvx.common.logger.StreamLogSink(*, logger_name='mvx.stream_log_sink', config=None)

Ready-to-use synchronous sink for standard streams.

StreamLogSink owns an internal logging.Logger configured by LoggingStreamConfig. It delivers prepared LogEvent objects to the configured standard stream.

Create a stream sink.

Parameters:

logger_name (str) – name assigned to the internal standard-library logger.
config (LoggingStreamConfig | None) – optional stream logging configuration. If omitted, a default LoggingStreamConfig is used.

Raises:

TypeError – if an argument has an invalid type.
ValueError – if logger_name is None or empty.

classmethod build_descriptor(**kwargs)

Build a descriptor for a stream sink configuration.

The descriptor is used by the package-level sink registry to detect idempotent configuration requests and conflicts.

Parameters:

kwargs (Any) – stream sink construction arguments.

Return type:

LogSinkDescriptor

Returns:

stream sink descriptor.

Raises:

TypeError – if an argument has an invalid type.
ValueError – if logger_name is None or empty.

classmethod create(**kwargs)

Create a stream sink and its terminator.

Parameters:: kwargs (Any) – arguments passed to StreamLogSink.
Return type:: tuple[LogSinkProto, Callable[[], None]]
Returns:: pair containing the created sink and an idempotent terminator.

log(event)

Deliver a prepared log event to the configured stream.

Calls made after close() are ignored.

Parameters:: event (LogEvent) – prepared event to deliver.
Return type:: None
Returns:: None.

close()

Close this sink.

The method removes the installed handler from the internal logger. Standard output and error streams are detached but not closed. Repeated calls are ignored.

Return type:: None
Returns:: None.

Package-level registration

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

from mvx.common.logger import configure_log_sink, StreamLogSink

sink = configure_log_sink(
    name="stderr",
    sink_cls=StreamLogSink,
)

If no configuration is supplied, StreamLogSink uses a default LoggingStreamConfig targeting stderr.

Custom stream configuration

Use LoggingStreamConfig to choose the stream target and standard logging settings.

from mvx.common.logger import (
    LogLevel,
    LogStreamOutput,
    LoggingStreamConfig,
    StreamLogSink,
    configure_log_sink,
)

config = LoggingStreamConfig(
    stream_output=LogStreamOutput.STDOUT,
    level=LogLevel.INFO,
)

sink = configure_log_sink(
    name="stdout",
    sink_cls=StreamLogSink,
    config=config,
)

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

Handler behavior

LoggingStreamConfig creates a standard-library logging.StreamHandler.

When applied to the internal logger, the configuration:

creates the 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.

Descriptor behavior

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

For stream sinks, the descriptor identity includes:

sink type
logger name
stream target
level
format settings
filter types

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 stream sink configuration.

Closing behavior

StreamLogSink.close() removes the installed handler from the internal logger.

For standard output and standard error, streams are detached but not closed.

Repeated close() calls are ignored.

The package-level sink terminator returned by StreamLogSink.create() is also idempotent.