Skip to content

xtr_logging

Channels, handlers, processors and formatters, behind one logger interface.

Code logs through :class:LoggerInterface. A :class:Logger is one channel: it turns each call into an immutable :class:LogRecord, runs its processors, and offers the record to a stack of handlers, which format it and write it somewhere — stopping where a handler does not let it bubble.

:class:LoggingConfig describes channels, handlers and processors as data, and :class:LoggerFactory builds loggers from it. The per-type configurations live in :mod:xtr_logging.config; the standard-library bridge in :mod:xtr_logging.bridge.stdlib.

The contract itself — :class:LoggerInterface, :class:Level, :class:NullLogger and what else a caller needs to log — lives in xtr-logging-contracts, so a library can depend on it without depending on any of this. It is imported from there, and neither redefined nor re-exported here: one place per name is what lets a container register a logger under the interface and have a library that never imported this package receive it.

Normalized

Normalized = 'bool | int | float | str | list[Normalized] | dict[str, Normalized] | None'

A value JSON can hold: what :meth:Normalizer.normalize returns.

LoggingConfig

Bases: Struct

The channels, handlers and processors of an application.

Checked as it is made: every handler a wrapper names must exist, wrappers must not nest each other in a loop, and a processor may only target a channel or handler that exists.

Attributes:

  • handlers (dict[str, HandlerConfig]) –

    Named handlers, in declaration order. Wrappers name the handlers they wrap; those leave every channel's stack.

  • channels (tuple[str, ...]) –

    Channels beyond :attr:default_channel. Channels named in a handler's channels list are declared too.

  • processors (tuple[ProcessorConfig, ...]) –

    Processors and where they run. By default one redacting processor, masking secret keys, URL credentials and secret query values; a configuration naming its own processors replaces it, so list a RedactingProcessorConfig there to keep it.

  • default_channel (str) –

    The channel a logger is on when none is asked for.

  • capture (CaptureConfig | None) –

    Send the standard library's logging into channels, and only there. Off when omitted.

all_channels property

all_channels: tuple[str, ...]

Every declared channel: the default, the listed, then those named by handlers.

nested_handlers property

nested_handlers: frozenset[str]

Handlers kept off every channel's stack: those named by another, or marked nested.

top_level_handlers property

top_level_handlers: tuple[str, ...]

Handlers on the channel stacks, highest priority first, ties in declaration order.

from_mapping classmethod

from_mapping(data: Mapping[str, object]) -> LoggingConfig

Read configuration from plain data — parsed TOML, JSON or YAML.

Values are not coerced: "3" is not a number. Levels are written by name ("error") or value (400).

Raises:

with_channels

with_channels(*channels: str) -> LoggingConfig

Return a copy that declares channels as well.

A channel already declared — listed, the default one, or named by a handler — is not added twice, and a copy with nothing to add is this very config. This is how a bundle gives itself a channel from prepend_extension::

builder.prepend_extension_config(LoggingConfig, lambda c: c.with_channels("mail"))

with_handler

with_handler(name: str, handler: HandlerConfig) -> LoggingConfig

Return a copy that holds handler under name as well.

A name the application already gave a handler is left to the application's: the copy is this very config. This is how a bundle adds a handler of its own from prepend_extension::

builder.prepend_extension_config(
    LoggingConfig, lambda c: c.with_handler("audit", ServiceHandlerConfig(id="audit"))
)

Services dataclass

Services(handlers: Mapping[str, HandlerInterface] = _no_handlers(), formatters: Mapping[str, FormatterInterface] = _no_formatters(), processors: Mapping[str, ProcessorInterface] = _no_processors(), activation_strategies: Mapping[str, ActivationStrategyInterface] = _no_strategies(), error_handlers: Mapping[str, Callable[[Exception, LogRecord], None]] = _no_error_handlers())

Objects a configuration can name but not describe.

Configuration is data, and some things are objects — a handler for a service this library does not ship, a formatter of your own. Hand them over here under an id, and name that id in the configuration::

LoggerFactory(
    LoggingConfig(handlers={"sentry": ServiceHandlerConfig(id="sentry")}),
    services=Services(handlers={"sentry": SentryHandler(dsn)}),
)

Attributes:

CaptureConflictError

CaptureConflictError(handler: str)

Bases: LoggingError

Capture is on while a stdlib handler sends records back into the standard library.

While capture owns the standard library's output, a record handed to it arrives at the capture — which drops it, rather than send it round again — and nothing else is left to write it. The record would be lost, so the combination is refused.

Record the handler that conflicts with capture.

CircularHandlerReferenceError

CircularHandlerReferenceError(path: tuple[str, ...])

Bases: LoggingError

Handlers nest each other in a loop, so none of them can be built first.

Record the loop, starting and ending on the same handler.

EmptyStackError

EmptyStackError(owner: str, stack: str)

Bases: LoggingError

Something was popped off a stack that holds nothing.

Raised by pop_handler and pop_processor. Popping more than was pushed is always a bug in the code doing it, so it is refused rather than answered with None.

Record what was popped from, and which of its stacks was empty.

InvalidConfigurationError

InvalidConfigurationError(detail: str)

Bases: LoggingError

Configuration data — parsed from a file or an environment — does not fit the schema.

detail names what is wrong and where, as a JSON path: an unknown key, a value of the wrong type, a level that does not exist.

Record what is wrong, and where.

InvalidOptionError

InvalidOptionError(option: str, value: str, reason: str)

Bases: LoggingError, ValueError

An option was given a value it cannot work with.

Raised where the value is given — a constructor or a configuration entry — rather than on the first record that would have exposed it.

Record the option, the value it was given, and why that is refused.

MixedChannelFilterError

MixedChannelFilterError(channels: tuple[str, ...])

Bases: LoggingError, ValueError

A handler's channel list mixes included (foo) and excluded (!foo) channels.

"Only foo" and "all but bar" cannot both be true, and guessing which was meant routes records wrongly. A :class:ValueError too, so a configuration parser reports where it is.

Record the list that mixes both forms.

NotProcessableHandlerError

NotProcessableHandlerError(handler: str)

Bases: LoggingError

A processor targets a handler that runs no processors of its own.

Record the handler that cannot take a processor.

UnknownChannelError

UnknownChannelError(channel: str, known: tuple[str, ...])

Bases: LoggingError

A logger was asked for on a channel the configuration does not declare.

Refused rather than created on the fly: a channel nobody declared has no handlers routed to it by name, so its records would go wherever the catch-all handlers send them — usually not where the caller expected.

Record the channel asked for, and those that exist.

UnknownHandlerError

UnknownHandlerError(name: str, referenced_by: str, known: tuple[str, ...])

Bases: LoggingError

A handler was named that the configuration does not define.

Raised as the configuration is made — for a wrapper whose nested handler or member is missing, or a processor targeting one — and by a factory asked for a handler by a name it never built.

Record the missing name, who asked for it, and what is defined.

UnknownServiceError

UnknownServiceError(kind: str, service_id: str, known: tuple[str, ...])

Bases: LoggingError

Configuration names a service that was not supplied.

A service is an object handed to the factory by id: a handler, formatter, processor or activation strategy.

Record what kind of service, its id, and the ids supplied for that kind.

ConsoleFormatter

ConsoleFormatter(format: str | None = None, date_format: str | None = None, *, allow_inline_line_breaks: bool = False, ignore_empty_context_and_extra: bool = True, include_stacktraces: bool = False, colors: bool = False, max_depth: int | None = None, max_items: int | None = None)

Bases: LineFormatter

A compact line for a terminal, with the level name coloured on request.

Shorter than :class:LineFormatter's default — a wall-clock time rather than a full timestamp, the channel in brackets — because a console shows logs as they happen rather than for archiving, and an empty context or extra is left off by default for the same reason.

With colors on, the level name is wrapped in an ANSI colour graded by severity; a :class:~xtr_logging.handler.console_handler.ConsoleHandler turns it on only when it is writing to a real terminal.

Configure the line, defaulting to the short console format.

Parameters:

  • format (str | None, default: None ) –

    The template; a short console line when omitted.

  • date_format (str | None, default: None ) –

    A :meth:~datetime.datetime.strftime format; %H:%M:%S when omitted.

  • allow_inline_line_breaks (bool, default: False ) –

    Keep line breaks inside values.

  • ignore_empty_context_and_extra (bool, default: True ) –

    Leave an empty context or extra off the line rather than printing []; on by default here.

  • include_stacktraces (bool, default: False ) –

    Print an exception's traceback after it.

  • colors (bool, default: False ) –

    Wrap the level name in an ANSI colour graded by severity.

  • max_depth (int | None, default: None ) –

    How deeply a nested value is rendered before it is cut; the normalizer's default when omitted.

  • max_items (int | None, default: None ) –

    How many items of one collection are rendered; the normalizer's default when omitted.

FormatterInterface

Bases: Protocol

Renders records as text.

format

format(record: LogRecord) -> str

Render one record.

format_batch

format_batch(records: Sequence[LogRecord]) -> str

Render several records as one piece of text, for handlers that send in bulk.

JsonBatchMode

Bases: IntEnum

How JsonFormatter.format_batch renders several records together.

JSON renders the batch as a single JSON array, which a reader parses in one call. NEWLINES renders one JSON object per line — the newline-delimited JSON that log shippers and jq expect.

JsonFormatter

JsonFormatter(batch_mode: JsonBatchMode = JsonBatchMode.NEWLINES, *, append_newline: bool = True, ignore_empty_context_and_extra: bool = False, include_stacktraces: bool = False, date_format: str | None = None, max_depth: int | None = None, max_items: int | None = None)

Bases: FormatterInterface

Renders a record as a single JSON object, one per line by default.

The object carries message, context, level (the numeric value), level_name, channel, datetime and extra, in that order, so a log shipper can rely on the shape. Values are reduced to plain JSON by :class:~xtr_logging.formatter.normalizer.Normalizer, an exception becoming the structure it describes.

A batch is either one JSON array or one object per line, per :class:JsonBatchMode — the latter being the newline-delimited JSON that log shippers ingest.

Configure the JSON.

Parameters:

  • batch_mode (JsonBatchMode, default: NEWLINES ) –

    Whether :meth:format_batch yields one object per line — exactly what formatting each record would — or one array.

  • append_newline (bool, default: True ) –

    End each formatted record with a newline, so a file handler writes one object per line.

  • ignore_empty_context_and_extra (bool, default: False ) –

    Leave context or extra out entirely when empty, rather than writing {}.

  • include_stacktraces (bool, default: False ) –

    Give an exception its traceback.

  • date_format (str | None, default: None ) –

    A :meth:~datetime.datetime.strftime format for the timestamp; ISO 8601 when omitted.

  • max_depth (int | None, default: None ) –

    How deeply a nested value is rendered before it is cut; the normalizer's default when omitted.

  • max_items (int | None, default: None ) –

    How many items of one collection are rendered; the normalizer's default when omitted.

format

format(record: LogRecord) -> str

Render record as one JSON object.

format_batch

format_batch(records: Sequence[LogRecord]) -> str

Render records as one object per line, or as one JSON array.

Either ends with a newline when append_newline is on, so batch after batch written to one file stays one per line.

LineFormatter

LineFormatter(format: str | None = None, date_format: str | None = None, *, allow_inline_line_breaks: bool = False, allow_control_characters: bool = False, ignore_empty_context_and_extra: bool = False, include_stacktraces: bool = False, max_depth: int | None = None, max_items: int | None = None)

Bases: FormatterInterface

Renders a record by substituting %token% placeholders in a format.

Tokens: %datetime%, %channel%, %level_name%, %level%, %message%, %context% and %extra% — the latter two as JSON — plus %context.KEY% and %extra.KEY% for one entry, which is then left out of the JSON so it is not printed twice.

Line breaks inside values — the Unicode line and paragraph separators included — become spaces unless allow_inline_line_breaks, so one record stays one line and a log can be read with grep. With include_stacktraces an exception printed by %context.KEY% or %extra.KEY% keeps the breaks of its traceback, and only it: a value some caller supplied never gets to start a line. Other control characters — an escape sequence that could clear a terminal or forge a line, a bidirectional override — are stripped unless allow_control_characters. An exception in context prints as [object] (Class: message at file:line).

Configure the line.

Parameters:

  • format (str | None, default: None ) –

    The template; :attr:SIMPLE_FORMAT when omitted.

  • date_format (str | None, default: None ) –

    A :meth:~datetime.datetime.strftime format; ISO 8601 when omitted.

  • allow_inline_line_breaks (bool, default: False ) –

    Keep line breaks inside values.

  • allow_control_characters (bool, default: False ) –

    Keep control characters inside values, rather than stripping the ones that could clear a terminal or forge a log line.

  • ignore_empty_context_and_extra (bool, default: False ) –

    Print nothing, rather than [], for an empty %context% or %extra%.

  • include_stacktraces (bool, default: False ) –

    Print an exception's traceback after it. Turns on line breaks for that one keyed value, which a traceback needs; every other value stays on its line.

  • max_depth (int | None, default: None ) –

    How deeply a nested value is rendered before it is cut; the normalizer's default when omitted.

  • max_items (int | None, default: None ) –

    How many items of one collection are rendered; the normalizer's default when omitted.

format

format(record: LogRecord) -> str

Render record as one line — or more, if line breaks are allowed.

format_batch

format_batch(records: Sequence[LogRecord]) -> str

Render each record and join them.

Normalizer

Normalizer(date_format: str | None = None, *, max_depth: int | None = None, max_items: int | None = None, include_stacktraces: bool = False)

Turns anything a caller logged into plain data.

Context is data from the caller, never a reason to fail: a value that cannot be serialised is described instead. Nesting deeper than max_depth, or a collection longer than max_items, is cut short with a note saying so, so one enormous value cannot stall a handler.

Subclass to render a kind of value differently; formatters override :meth:_normalize_exception to print exceptions their own way.

Configure how values are reduced.

Parameters:

  • date_format (str | None, default: None ) –

    A :meth:~datetime.datetime.strftime format for datetimes; ISO 8601 when omitted.

  • max_depth (int | None, default: None ) –

    How deeply nested a value may be before it is cut; a sensible default when omitted.

  • max_items (int | None, default: None ) –

    How many items of one collection are kept; a sensible default when omitted.

  • include_stacktraces (bool, default: False ) –

    Whether an exception carries its traceback.

normalize

normalize(value: object) -> Normalized

Reduce value to plain data.

format_datetime

format_datetime(value: datetime) -> str

Render value with :attr:date_format, or as ISO 8601.

AbstractHandler

AbstractHandler(level: LevelLike = Level.DEBUG, bubble: bool = True)

Bases: HandlerInterface, ResetInterface, ABC

A handler with a minimum level and a bubble flag.

Handles records at level or above. With bubble on — the default — a record it handles still reaches the handlers after it; turned off, the record stops here.

Handle records at level or above, letting them bubble on if bubble.

Raises:

  • InvalidLevelError –

    If level names no level.

level property

level: Level

The least severe level this handler handles.

bubble property

bubble: bool

Whether a handled record goes on to the next handler.

set_level

set_level(level: LevelLike) -> None

Handle records at level or above from now on.

Raises:

  • InvalidLevelError –

    If level names no level.

is_handling

is_handling(record: LogRecord) -> bool

Whether record is at this handler's level or above.

handle abstractmethod

handle(record: LogRecord) -> bool

Handle record; return True to stop it bubbling.

handle_batch

handle_batch(records: Sequence[LogRecord]) -> None

Handle each record in turn.

close

close() -> None

Release nothing; handlers holding resources override this.

reset async

reset() -> None

Forget nothing; handlers holding per-unit-of-work state override this.

AbstractProcessingHandler

AbstractProcessingHandler(level: LevelLike = Level.DEBUG, bubble: bool = True)

Bases: AbstractHandler, ProcessorStack, FormattableHandlerInterface, ABC

Handles a record by processing it, formatting it, then writing the text.

Subclasses implement :meth:write alone, and override :meth:default_formatter if a line of text is the wrong default.

Handle records at level or above, letting them bubble on if bubble.

formatter property writable

formatter: FormatterInterface

The formatter in use, built from :meth:default_formatter on first use.

handle

handle(record: LogRecord) -> bool

Process, format and write record if it is at this handler's level.

reset async

reset() -> None

Reset every processor of this handler that holds state.

default_formatter

default_formatter() -> FormatterInterface

The formatter used until another is set: one line of text per record.

write abstractmethod

write(record: LogRecord, formatted: str) -> None

Write formatted, the rendering of record, wherever this handler writes.

ActivationStrategyInterface

Bases: Protocol

Decides, from a single record, whether buffering should stop and flush.

A fingers-crossed handler holds everything back until something worth keeping happens. The strategy is that judgement, kept apart from the handler so the same handler can trigger on an error level, on a per-channel level, or on anything else a caller can express.

is_handler_activated

is_handler_activated(record: LogRecord) -> bool

Whether record is the one that should release the buffer.

BufferHandler

BufferHandler(handler: HandlerInterface, buffer_limit: int = 10000, level: LevelLike = Level.DEBUG, bubble: bool = True, flush_on_overflow: bool = False)

Bases: AbstractHandler, ProcessorStack

Keeps records in memory and forwards them together when flushed.

A mail handler that sent one message per record would send a flood; wrap it in one of these and it sends a single message per request instead. The buffer is handed on as a batch on :meth:close, on :meth:reset, or when it overflows a limit that flushes rather than discards.

It never registers an atexit hook of its own: the process that owns the buffer — the logger factory, usually — flushes it by calling :meth:close, so nothing is written after interpreter shutdown has begun.

Buffer records for handler.

Parameters:

  • handler (HandlerInterface) –

    Where the buffer is flushed to, as a batch.

  • buffer_limit (int, default: 10000 ) –

    The most records to hold; 0 means no limit. Bounded at 10_000 by default. Past it, the oldest record is dropped unless flush_on_overflow.

  • level (LevelLike, default: DEBUG ) –

    Buffer only records at this level or above.

  • bubble (bool, default: True ) –

    Whether a buffered record still reaches later handlers.

  • flush_on_overflow (bool, default: False ) –

    Flush the whole buffer when it fills, rather than dropping the oldest record to make room.

Raises:

  • InvalidLevelError –

    If level names no level.

handle

handle(record: LogRecord) -> bool

Buffer record if it is at this handler's level.

Returns True only when bubble is off, exactly as any handler that has taken a record does — the record is buffered, not yet written. A record arriving in a unit of work that is over — replayed by a queue once it ended — is forwarded at once, as the unit's end would have.

flush

flush() -> None

Hand the whole buffer to the wrapped handler, then empty it.

clear

clear() -> None

Empty the buffer without forwarding anything.

close

close() -> None

Flush what is buffered, then close the wrapped handler.

reset async

reset() -> None

Flush the buffer and reset this handler's processors and the wrapped one.

ChannelLevelActivationStrategy

ChannelLevelActivationStrategy(default_action_level: LevelLike, channel_to_action_level: Mapping[str, LevelLike] | None = None)

Bases: ActivationStrategyInterface

Releases the buffer on a level that varies by channel.

One request touches many channels, and they do not all deserve the same alarm. Trigger on ERROR everywhere by default, say, but on WARNING for a channel where a warning is already worth the whole log.

Activate on default_action_level, or a channel's own level where given.

Raises:

  • InvalidLevelError –

    If any level names no level.

is_handler_activated

is_handler_activated(record: LogRecord) -> bool

Whether record reaches the level its channel activates on.

ConsoleHandler

ConsoleHandler(stream: IO[str] | None = None, verbosity: Verbosity = Verbosity.NORMAL, verbosity_levels: Mapping[Verbosity, LevelLike] | None = None, bubble: bool = True)

Bases: AbstractProcessingHandler

Writes to a console, at a level set by how verbose the command is.

A console command chooses its verbosity from its -v flags; this handler turns that into a log level, so -vv surfaces info, a quiet run shows only errors and a silent one nothing at all. The level is recomputed whenever the verbosity is set, which a command does once it has parsed its input.

The stream defaults to standard error, resolved at write time so a test that swaps sys.stderr is written to, and colours are on only when that stream is a real terminal. :meth:set_stream moves both, as a console application does to follow the output of the command it runs.

Write to stream at the level verbosity maps to.

Parameters:

  • stream (IO[str] | None, default: None ) –

    Where to write; standard error, resolved at write time, when omitted.

  • verbosity (Verbosity, default: NORMAL ) –

    The verbosity the command is running at.

  • verbosity_levels (Mapping[Verbosity, LevelLike] | None, default: None ) –

    Overrides for the verbosity-to-level map; the keys given replace the defaults, the rest stand. :attr:Verbosity.SILENT prints nothing, whatever it maps to.

  • bubble (bool, default: True ) –

    Let a handled record reach later handlers.

verbosity property

verbosity: Verbosity

The verbosity the handler is printing at.

set_verbosity

set_verbosity(verbosity: Verbosity) -> None

Print at the level verbosity maps to from now on.

set_stream

set_stream(stream: IO[str] | None, *, colors: bool | None = None) -> None

Write to stream from now on.

Parameters:

  • stream (IO[str] | None) –

    Where to write; standard error, resolved at write time, when None.

  • colors (bool | None, default: None ) –

    Colour the level names, or not; None colours them only on a real terminal. A formatter set by hand is kept as it is.

is_handling

is_handling(record: LogRecord) -> bool

Whether record is at the level, and the command is not silent.

write

write(record: LogRecord, formatted: str) -> None

Write formatted to the stream, or to standard error.

default_formatter

default_formatter() -> FormatterInterface

A short console line, coloured as :meth:set_stream said, or on a real terminal.

DebugHandler

DebugHandler(level: LevelLike = Level.DEBUG)

Bases: AbstractHandler

Keeps the records of a unit of work that asked for them, and nothing anywhere else.

A profiler shows the log of one request beside its other panels: this handler is how it gets that log. Records are kept per :mod:unit of work <xtr_logging.log_unit>, so requests served at once each keep their own, and the list is let go of when the unit ends — a long-running process never accumulates them. A unit keeps its records only once :meth:begin was called in it — by the tool that reads them, for the units it shows — so a unit nobody reads, a long command logging for hours, keeps nothing. Outside a unit nothing is kept.

It always bubbles, whatever bubble says, because keeping a copy for a debugging tool must never take a record away from the handlers that write it.

Keep the records at level or above.

Raises:

  • InvalidLevelError –

    If level names no level.

handle

handle(record: LogRecord) -> bool

Keep record in the open unit when it began recording, and let it bubble on.

begin

begin() -> None

Start keeping the open unit's records, from none; do nothing outside a unit.

is_recording

is_recording() -> bool

Tell whether the open unit keeps its records.

get_logs

get_logs() -> tuple[LogRecord, ...]

Return the records of the open unit, oldest first; none outside a unit.

count_errors

count_errors() -> int

Return how many records of the open unit are at ERROR or above.

DeduplicationHandler

DeduplicationHandler(handler: HandlerInterface, store: str | PathLike[str] | None = None, deduplication_level: LevelLike = Level.ERROR, time: int = 60, bubble: bool = True, *, clock: ClockInterface | None = None, buffer_limit: int = 10000, flush_on_overflow: bool = False, name: str = '')

Bases: BufferHandler

Stops the same alert going out twice when one failure floods the logs.

A database going down can fail every request the same way; without this a mail or chat handler would send the identical error hundreds of times. Records are buffered like :class:BufferHandler, and on flush each one at or above deduplication_level is checked against a small file of what was recently sent — matched by level and a digest of the message's first line, within time seconds. The batch goes out whole, with the records below that level that explain it, when any of them is new or none reaches the level; it is dropped whole when every one of them is a repeat.

The store defaults to a file named after the wrapped handler — its class, level and target — in a directory of the temporary one made for this user alone: another user can neither read what was sent nor plant a file there. One owned by someone else is not used, and nothing is deduplicated. Give store an explicit path shared across processes so a burst spread over many workers is still deduplicated: the store is locked while it is read and written, where the system has file locks. A missing directory for it is made, for this user alone, on first use. The clock is injected so a test can decide what "recently" means.

Records are held until a flush, all of them unless buffer_limit caps how many, the oldest dropped past it — or everything forwarded, with flush_on_overflow.

Deduplicate what handler sends.

Parameters:

  • handler (HandlerInterface) –

    The handler whose output is deduplicated.

  • store (str | PathLike[str] | None, default: None ) –

    The file recording what was recently sent; a temp-directory default is used when None.

  • deduplication_level (LevelLike, default: ERROR ) –

    Only records at this level or above are considered for suppression.

  • time (int, default: 60 ) –

    How many seconds a record suppresses later duplicates of itself.

  • bubble (bool, default: True ) –

    Whether buffered records still reach later handlers.

  • clock (ClockInterface | None, default: None ) –

    Where "now" is read from, for expiry; the clock in force by default.

  • buffer_limit (int, default: 10000 ) –

    The most records held until a flush — ten thousand by default, so one failure flooding the logs cannot fill the memory; 0 holds them all.

  • flush_on_overflow (bool, default: False ) –

    Forward the held records when buffer_limit is reached, rather than dropping the oldest.

  • name (str, default: '' ) –

    Tells the default store apart from that of another handler wrapping one alike — same class, level and target; a configuration gives each handler its name.

Raises:

  • InvalidLevelError –

    If deduplication_level names no level.

ErrorHandlerInterface

Bases: Protocol

Receives a failure the queue handler's worker caught, and the record behind it.

The worker must outlive a broken handler, so it cannot let the exception rise; it reports it here instead. A plain function with this signature is one: register it as a service of this type under the id a queue handler's on_error names.

ErrorLevelActivationStrategy

ErrorLevelActivationStrategy(action_level: LevelLike)

Bases: ActivationStrategyInterface

Releases the buffer once a record reaches action_level.

The default a fingers-crossed handler falls back to: keep the whole request's log only when an error — or whatever level was named — actually occurred.

Activate on records at action_level or above.

Raises:

  • InvalidLevelError –

    If action_level names no level.

is_handler_activated

is_handler_activated(record: LogRecord) -> bool

Whether record is at action_level or above.

FallbackGroupHandler

FallbackGroupHandler(handlers: Sequence[HandlerInterface], bubble: bool = True)

Bases: GroupHandler

Tries each member in turn until one handles a record without raising.

A primary handler with backups: send to the network service, fall back to a local file if it is down, fall back to stderr if even that fails. The last failure is re-raised rather than swallowed — if every backup is broken the caller should hear about it, through the logger's own exception handler, rather than lose the record in silence.

Only a failure moves on to the next member: one that returns without handling — the record below its level — ends the search as a success. Filter by level on the group, not on its members.

handle

handle(record: LogRecord) -> bool

Offer record to each member until one succeeds; re-raise if none do.

Raises:

  • Exception –

    The failure of the last member, if every member raised.

handle_batch

handle_batch(records: Sequence[LogRecord]) -> None

Offer the batch to each member until one succeeds; re-raise if none do.

Raises:

  • Exception –

    The failure of the last member, if every member raised.

FilterHandler

FilterHandler(handler: HandlerInterface | _HandlerFactory, min_level_or_list: LevelLike | Sequence[LevelLike] = Level.DEBUG, max_level: LevelLike = Level.EMERGENCY, bubble: bool = True)

Bases: ProcessorStack, LazyHandler, HandlerInterface, ResetInterface

Forwards only records whose level is in an accepted set.

A handler's minimum level lets everything above it through; this instead carves out a band — a file of just notices and warnings, say, with errors left to a handler that pages someone. Give it a min/max pair or an explicit list of levels.

The wrapped handler may be a factory handler(record, self), resolved and cached the first time a record actually needs it.

Wrap handler, accepting a band or a list of levels.

Parameters:

  • handler (HandlerInterface | _HandlerFactory) –

    The handler forwarded to, or a factory that builds it.

  • min_level_or_list (LevelLike | Sequence[LevelLike], default: DEBUG ) –

    The lowest level to accept, or an explicit list of the only levels to accept.

  • max_level (LevelLike, default: EMERGENCY ) –

    The highest level to accept; ignored when a list was given.

  • bubble (bool, default: True ) –

    Whether accepted records still reach later handlers.

Raises:

  • InvalidLevelError –

    If any level names no level.

accepted_levels property

accepted_levels: tuple[Level, ...]

The levels let through, least severe first.

set_accepted_levels

set_accepted_levels(min_level_or_list: LevelLike | Sequence[LevelLike] = Level.DEBUG, max_level: LevelLike = Level.EMERGENCY) -> None

Accept a band from min_level_or_list to max_level, or an exact list.

Raises:

  • InvalidLevelError –

    If any level names no level.

is_handling

is_handling(record: LogRecord) -> bool

Whether record's level is one this handler accepts.

handle

handle(record: LogRecord) -> bool

Forward record if its level is accepted, after this handler's processors.

handle_batch

handle_batch(records: Sequence[LogRecord]) -> None

Forward the accepted records of records as one batch, after its own processors.

reset async

reset() -> None

Reset this handler's processors and the wrapped handler.

close

close() -> None

Close the wrapped handler.

FingersCrossedHandler

FingersCrossedHandler(handler: HandlerInterface | _HandlerFactory, activation_strategy: ActivationStrategyInterface | LevelLike | None = None, buffer_size: int = 10000, bubble: bool = True, stop_buffering: bool = True, passthru_level: LevelLike | None = None)

Bases: ProcessorStack, LazyHandler, HandlerInterface, ResetInterface

Buffers every record, and forwards the lot the moment one is bad enough.

A healthy request leaves nothing in the log; a failed one leaves its whole story, context and all, not just the line that failed. The activation strategy decides what "bad enough" means. After it fires, records pass straight through — unless stop_buffering is off, which starts a fresh buffer for whatever follows.

passthru_level is the floor kept even when nothing triggered: on :meth:close or :meth:reset, records at that level or above are still forwarded, so a warning is not lost just because no error joined it.

The wrapped handler may be given as a factory handler(record, self) -> HandlerInterface, resolved and cached the first time it is needed — so an expensive handler is never built for a request that stays quiet.

Wrap handler behind a buffer released by activation_strategy.

Parameters:

  • handler (HandlerInterface | _HandlerFactory) –

    The handler flushed to, or a factory that builds it lazily.

  • activation_strategy (ActivationStrategyInterface | LevelLike | None, default: None ) –

    What releases the buffer — a strategy, or a level for :class:ErrorLevelActivationStrategy. Defaults to activating on WARNING and above.

  • buffer_size (int, default: 10000 ) –

    The most records to keep before the oldest are dropped; 0 keeps everything until activation. Bounded at 10_000 by default.

  • bubble (bool, default: True ) –

    Whether records still reach later handlers.

  • stop_buffering (bool, default: True ) –

    Whether to pass records straight through once activated, rather than buffering a fresh batch.

  • passthru_level (LevelLike | None, default: None ) –

    A floor always flushed on close or reset, even with no activation; None flushes nothing in that case.

Raises:

  • InvalidLevelError –

    If a level argument names no level.

is_handling

is_handling(record: LogRecord) -> bool

Always True: everything is buffered until the buffer is released.

handle

handle(record: LogRecord) -> bool

Buffer record, or pass it through once the buffer has been released.

A record arriving in a unit of work that is over — replayed by a queue once it ended — is handled at once as the unit's end would handle it: passed on if it activates, or if the passthru floor keeps it, dropped otherwise.

handle_batch

handle_batch(records: Sequence[LogRecord]) -> None

Offer each record in turn, as a logger would one by one.

activate

activate() -> None

Release the buffer now, whatever the strategy would have said.

close

close() -> None

Flush the passthru floor, then close the wrapped handler.

reset async

reset() -> None

Flush the passthru floor, reset processors, and reset the wrapped handler.

clear

clear() -> None

Drop the buffer without forwarding it, and start buffering afresh.

FormattableHandlerInterface

Bases: Protocol

Renders records through a formatter that can be swapped.

formatter property writable

formatter: FormatterInterface

The formatter in use; a handler supplies its own default.

GroupHandler

GroupHandler(handlers: Sequence[HandlerInterface], bubble: bool = True)

Bases: ProcessorStack, HandlerInterface, ResetInterface

Forwards every record to each of a group of handlers.

One place to attach a file, a console and a syslog to a channel, treated as a single handler on its stack. Records are immutable, so nothing is cloned before it is handed on — every member sees the same record.

Forward to each of handlers, letting records bubble on if bubble.

handlers property

handlers: tuple[HandlerInterface, ...]

The handlers this group forwards to.

is_handling

is_handling(record: LogRecord) -> bool

Whether any member would handle record.

handle

handle(record: LogRecord) -> bool

Offer record to every member, after this handler's own processors.

handle_batch

handle_batch(records: Sequence[LogRecord]) -> None

Offer the whole batch to every member.

reset async

reset() -> None

Reset this handler's processors and every member that holds state.

close

close() -> None

Close every member.

HandlerInterface

Bases: Protocol

Receives records from a logger and does something with them.

A logger holds a stack of handlers and offers each record to them in turn. A handler that returns True from :meth:handle stops the record there — that is what bubble=False means — so a later handler never sees it.

is_handling

is_handling(record: LogRecord) -> bool

Whether :meth:handle would do anything with record.

Asked before processors run, so it must be cheap and must not depend on anything a processor adds. Usually just a level check.

handle

handle(record: LogRecord) -> bool

Handle record; return True to stop it reaching later handlers.

handle_batch

handle_batch(records: Sequence[LogRecord]) -> None

Handle several records at once, as a buffer flushes them.

close

close() -> None

Flush and release what the handler holds. It may be used again after.

NullHandler

NullHandler(level: LevelLike = Level.DEBUG)

Bases: AbstractHandler

Handles records at its level by discarding them, and never lets them bubble.

Put one on a channel to silence it, or low in a stack to stop what nothing above it wanted from reaching anything below.

Swallow records at level or above.

handle

handle(record: LogRecord) -> bool

Discard record; stop it if it is at this handler's level.

ProcessableHandlerInterface

Bases: Protocol

Runs processors on the records it handles, after the logger's own.

Handlers are shared between channels, so a processor attached here applies to records from every channel the handler serves.

push_processor

push_processor(processor: ProcessorInterface) -> None

Add processor in front of those already attached.

pop_processor

pop_processor() -> ProcessorInterface

Remove and return the processor added last.

Raises:

QueueHandler

QueueHandler(handler: HandlerInterface, *, max_size: int = 10000, on_error: Callable[[Exception, LogRecord], None] | None = None)

Bases: HandlerInterface, ResetInterface

Enqueues records and lets a worker thread do the writing.

Latency-sensitive or async code should not wait on a socket or a disk to log a line. This takes the record — safe to hand across threads, since a record is immutable — puts it on a queue, and returns at once; a daemon thread drains the queue into the wrapped handler.

A handler failing on the worker must not kill the worker, or every later record would be lost silently: the exception goes to on_error instead, which by default prints a traceback to standard error. Call :meth:flush to wait for the backlog to clear, and :meth:close to stop the thread and close the wrapped handler; the handler starts a fresh worker if it is used again afterwards.

Closing is serialised: a second :meth:close waits for the first rather than racing it for the worker, and a record logged while a close runs waits for it to finish, then goes to the fresh worker — it is never stranded on a queue nothing drains. What the worker itself logs while stopping is written before the wrapped handler closes.

Offload handler onto a background thread.

Parameters:

  • handler (HandlerInterface) –

    The handler the worker forwards records to.

  • max_size (int, default: 10000 ) –

    The most records to hold before :meth:handle blocks to apply backpressure; 0 means an unbounded queue that never blocks. Bounded at 10_000 by default, so a worker that cannot keep up applies backpressure rather than growing without limit.

  • on_error (Callable[[Exception, LogRecord], None] | None, default: None ) –

    Called with any exception the wrapped handler raises on the worker, and the record that caused it; a traceback is printed to standard error when this is None.

is_handling

is_handling(record: LogRecord) -> bool

Whether the wrapped handler would handle record.

handle

handle(record: LogRecord) -> bool

Enqueue record for the worker and return without waiting.

The caller's context is captured alongside the record only when there is logging state to carry — a unit of work is open, or the ambient log context is bound — so the worker writes it in the same unit it was logged from: a fingers-crossed handler behind the queue keeps a request's buffer for that request, not for whichever record the worker happens to drain next. With nothing bound there is nothing to copy, and the capture is skipped.

The record holds its unit open until the worker has written it, so a unit ending while its records are still queued closes once the last of them is written — on the worker, whose writing is then what the unit's end flushes: an error queued behind its unit's end still brings the unit's records with it, and nothing is stranded.

Always returns False: the record is only queued, so it must still reach the handlers after this one.

A record logged from the worker itself — a wrapped handler that logs about what it does — is written there and then, not queued: the worker is the queue's only reader, so putting into a full queue from it would wait forever. A record logged while such a record is being written goes to standard error, so a handler logging about its own logging cannot loop.

handle_batch

handle_batch(records: Sequence[LogRecord]) -> None

Enqueue each record in turn.

flush

flush() -> None

Block until every record queued so far has been handled.

A worker that died — a handler raising what is not an Exception — is started again while waiting, or the records it left would never be handled and this would wait forever.

reset async

reset() -> None

Handle every record queued so far, then reset the wrapped handler.

What the wrapped handler buffered for one unit of work — a fingers-crossed request log — must not reach the next.

close

close() -> None

Drain the queue, stop the worker, and close the wrapped handler.

RotatingFileHandler

RotatingFileHandler(filename: str | PathLike[str], max_files: int = 0, level: LevelLike = Level.DEBUG, bubble: bool = True, *, date_format: str = '%Y-%m-%d', filename_format: str = '{filename}-{date}', file_permission: int | None = None, clock: ClockInterface | None = None)

Bases: StreamHandler

Writes to a file whose name carries a date, switching when the date changes.

The date comes from the clock, not the record: a record carrying an old or forged timestamp lands in today's file, and never reopens yesterday's or sweeps today's away. app.log with the default format becomes app-2026-09-24.log — the extension kept, the date spliced into the stem.

When the date rolls over, the current file is closed and the next opened, and the directory is swept: the newest max_files files matching the pattern are kept and older ones deleted, unless max_files is zero, which keeps everything.

Rotate filename daily, keeping the newest max_files of them.

Parameters:

  • filename (str | PathLike[str]) –

    The base path; its stem and extension frame each dated file.

  • max_files (int, default: 0 ) –

    How many dated files to keep; zero keeps them all.

  • level (LevelLike, default: DEBUG ) –

    Handle records at this level or above.

  • bubble (bool, default: True ) –

    Let a handled record reach later handlers.

  • date_format (str, default: '%Y-%m-%d' ) –

    A :meth:~datetime.datetime.strftime format for the date.

  • filename_format (str, default: '{filename}-{date}' ) –

    A template with {filename} and {date}.

  • file_permission (int | None, default: None ) –

    The mode to chmod each file created to.

  • clock (ClockInterface | None, default: None ) –

    What today's date is read from; the clock in force when None.

Raises:

  • InvalidOptionError –

    If filename_format lacks {date} or date_format holds no strftime directive, or renders a path separator that would scatter the dated files across directories.

  • InvalidLevelError –

    If level names no level.

write

write(record: LogRecord, formatted: str) -> None

Write to the file for today's date, rotating first if it changed.

Deciding to rotate, rotating and writing happen under one lock: a thread seeing the new date half set would reopen the old file.

SamplingHandler

SamplingHandler(handler: HandlerInterface | _HandlerFactory, factor: int, bubble: bool = True, *, rng: Random | None = None)

Bases: AbstractHandler, ProcessorStack, LazyHandler

Forwards roughly one record in factor and drops the rest.

A high-frequency event does not need every occurrence logged; sampling keeps the volume — and the cost of the wrapped handler — down while still, by the law of large numbers, reflecting what is happening. The decision is random per record, so the sampled stream is approximate, not every Nth.

The random source is injected so a test can seed it and know exactly which records survive.

Sample about one record in factor for handler.

Parameters:

  • handler (HandlerInterface | _HandlerFactory) –

    The handler sampled records are forwarded to, or a factory.

  • factor (int) –

    The sampling divisor; 1 keeps everything, 10 keeps about a tenth.

  • bubble (bool, default: True ) –

    Let a sampled record reach later handlers.

  • rng (Random | None, default: None ) –

    The random source; a fresh :class:random.Random by default.

Raises:

is_handling

is_handling(record: LogRecord) -> bool

Whether the wrapped handler would handle record at all.

True while it is still to be built: sampling decides first, so a dropped record never costs building it.

handle

handle(record: LogRecord) -> bool

Forward record with probability 1 / factor; drop it otherwise.

reset async

reset() -> None

Reset this handler's processors and the wrapped handler.

close

close() -> None

Close the wrapped handler.

StreamHandler

StreamHandler(stream: TextIO | str | PathLike[str], level: LevelLike = Level.DEBUG, bubble: bool = True, *, file_permission: int | None = None, mode: Literal['a', 'w', 'x'] = 'a', encoding: str = 'utf-8', errors: str = 'backslashreplace')

Bases: AbstractProcessingHandler

Writes each formatted record to a stream, flushing as it goes.

Given an open stream it writes there and leaves closing to the caller. Given a path it opens the file on the first record — creating parent directories, and setting file_permission on the file whether it created it or found it — so a handler configured for a path that is never logged to touches nothing.

A lock serialises writes, so two threads logging at once cannot splice one line inside another. :meth:close closes only a file this handler opened; the next record reopens it.

Write to stream — an open stream, or a path opened on first use.

Parameters:

  • stream (TextIO | str | PathLike[str]) –

    An open text stream, or the path of a file to open.

  • level (LevelLike, default: DEBUG ) –

    Handle records at this level or above.

  • bubble (bool, default: True ) –

    Let a handled record reach later handlers.

  • file_permission (int | None, default: None ) –

    The mode a file this handler opens is set to, whether it created the file or found one already there; left at the system default when omitted.

  • mode (Literal['a', 'w', 'x'], default: 'a' ) –

    How to open a path — append, truncate, or create-exclusive.

  • encoding (str, default: 'utf-8' ) –

    How to encode text written to a path.

  • errors (str, default: 'backslashreplace' ) –

    What to do with text encoding cannot represent, as :func:open takes it; escaped by default, so a log call never fails over one character.

Raises:

  • InvalidLevelError –

    If level names no level.

url property

url: str | None

The path this handler writes to, or None if it was given a stream.

stream property

stream: TextIO | None

The open stream, or None before the first write or after :meth:close.

write

write(record: LogRecord, formatted: str) -> None

Write formatted to the stream, opening a configured path if need be.

handle_batch

handle_batch(records: Sequence[LogRecord]) -> None

Format the records it handles as one batch, and write it at once.

The formatter decides what a batch looks like — one JSON array, say, with batch_mode="json"; by default the same text as record by record.

close

close() -> None

Close a file this handler opened; leave a stream it was handed alone.

SyslogHandler

SyslogHandler(ident: str = 'python', facility: int | str = 'user', level: LevelLike = Level.DEBUG, bubble: bool = True, *, address: str | tuple[str, int] = ('localhost', 514), socktype: int | None = None, timeout: float | None = None)

Bases: AbstractProcessingHandler

Sends each record to a syslog daemon with its RFC 5424 severity.

The transport is the standard library's SysLogHandler, opened on the first record and closed by :meth:close. Each record is handed to it as a synthetic stdlib record whose level name maps, through :attr:priority_map, to the syslog severity — so the datagram's priority is facility * 8 + severity with the severity this library assigns.

Send records to the syslog daemon at address under facility.

Parameters:

  • ident (str, default: 'python' ) –

    Prefixed to every line as ident:, naming the sender.

  • facility (int | str, default: 'user' ) –

    A syslog facility, by name ("user", "local0") or by its integer.

  • level (LevelLike, default: DEBUG ) –

    Handle records at this level or above.

  • bubble (bool, default: True ) –

    Let a handled record reach later handlers.

  • address (str | tuple[str, int], default: ('localhost', 514) ) –

    A (host, port) pair, or the path of a local socket.

  • socktype (int | None, default: None ) –

    A socket type; the stdlib default (UDP) when omitted.

  • timeout (float | None, default: None ) –

    Seconds a connect or send may block before failing; left at the system default (blocking) when omitted. Syslog carries no encryption: a datagram crosses the network in cleartext.

Raises:

  • InvalidOptionError –

    If facility names no known facility.

  • InvalidLevelError –

    If level names no level.

priority_map class-attribute

priority_map: Mapping[str, str] = _PRIORITY_MAP

Level name to syslog severity word, for every one of the eight levels.

write

write(record: LogRecord, formatted: str) -> None

Hand formatted to the transport with the record's severity.

close

close() -> None

Close the transport; the next record opens a fresh one.

default_formatter

default_formatter() -> FormatterInterface

A line without a datetime, since the syslog daemon stamps its own.

TestHandler

TestHandler(level: LevelLike = Level.DEBUG, bubble: bool = True)

Bases: AbstractProcessingHandler

Records everything it handles, and answers questions about it.

Put one on a logger under test instead of a file, then ask it what was logged::

handler = TestHandler()
Logger("app", [handler]).error("payment failed", {"order": 7})

assert handler.has_record_that_contains("payment", Level.ERROR)

Records are kept after processing, so a test sees what a real handler would have written; :attr:formatted holds the rendered text too.

Record everything at level or above.

records property

records: tuple[LogRecord, ...]

Every record handled, oldest first.

formatted property

formatted: tuple[str, ...]

The text each record was rendered to, oldest first.

clear

clear() -> None

Forget every record.

reset async

reset() -> None

Forget every record and reset the handler's processors.

has_records

has_records(level: LevelLike) -> bool

Whether anything was recorded at exactly level.

has_record

has_record(message: str, level: LevelLike, context: Context | None = None) -> bool

Whether a record at level has exactly message, and context if given.

has_record_that_contains

has_record_that_contains(fragment: str, level: LevelLike) -> bool

Whether a record at level has a message containing fragment.

has_record_that_matches

has_record_that_matches(pattern: str | Pattern[str], level: LevelLike) -> bool

Whether a record at level has a message matching pattern anywhere.

has_record_that_passes

has_record_that_passes(predicate: Callable[[LogRecord], bool], level: LevelLike) -> bool

Whether predicate holds for some record at exactly level.

write

write(record: LogRecord, formatted: str) -> None

Keep record and its rendering.

WhatFailureGroupHandler

WhatFailureGroupHandler(handlers: Sequence[HandlerInterface], bubble: bool = True)

Bases: GroupHandler

Forwards to every member, swallowing whatever any of them throws.

The opt-in "logging must never break the app" wrapper: a syslog socket that has gone away, or a disk that has filled, stops that one handler and no other. Failures are suppressed on purpose — there is nowhere left to report a logging failure to — so reach for this only at the outermost layer, never to paper over a handler that should be fixed.

handle

handle(record: LogRecord) -> bool

Offer record to every member, ignoring any that fail.

handle_batch

handle_batch(records: Sequence[LogRecord]) -> None

Offer the batch to every member, ignoring any that fail.

close

close() -> None

Close every member, ignoring any that fail.

LogRecord dataclass

LogRecord(datetime: datetime, channel: str, level: Level, message: str, context: Context = _EMPTY, extra: Context = _EMPTY)

One thing that was logged.

Immutable, so a record handed to several handlers — or to a queue that writes it later — cannot be changed under any of them. A processor returns a new record instead: :meth:with_extra for the common case, :func:dataclasses.replace for anything else.

context and extra are copied on the way in, so a caller mutating the dictionary it logged cannot rewrite history either.

Attributes:

  • datetime (datetime) –

    When the record was made, timezone-aware.

  • channel (str) –

    The name of the logger that made it.

  • level (Level) –

    How severe it is.

  • message (str) –

    What happened, possibly holding {placeholders}.

  • context (Context) –

    What the caller attached. An exception goes under :data:~xtr_logging_contracts.context.EXCEPTION_KEY.

  • extra (Context) –

    What processors attached. Kept apart from context so a processor can never overwrite something the caller said.

level_name property

level_name: str

The level's name in upper case, as formatters print it.

exception property

exception: BaseException | None

The exception under the exception key, if there is one.

with_extra

with_extra(values: Context) -> LogRecord

Return a copy with values merged into extra, winning on conflict.

The context is already a private frozen copy, so the new record shares it rather than copying it again on every processor.

LogUnitParticipant

Bases: UnitParticipantInterface

Opens a log unit as each unit of work begins, and closes it once the unit has ended.

So what is kept per unit — a fingers-crossed buffer, the id tying records together, values bound to the log context — is one request's, one message's, one command's, however many run at once. A unit opened inside another — a message handled inside a request — is a log unit of its own, and the one around it is open again once it ends.

The container closes a unit's scoped services before it tells this the unit ended, so what their teardown logs lands in the unit's log unit.

Registered by the logging bundle; outside a container, open and close units with :func:~xtr_logging.log_unit.begin_unit and :func:~xtr_logging.log_unit.end_unit instead.

unit_began

unit_began() -> object | None

Open the unit's log unit.

unit_ended

unit_ended(token: object | None) -> None

Close the unit's log unit, running what its end flushes.

Logger

Logger(name: str, handlers: Sequence[HandlerInterface] = (), processors: Sequence[ProcessorInterface] = (), *, clock: ClockInterface | None = None, exception_handler: Callable[[Exception, LogRecord], None] | None = None, detect_cycles: bool = True)

Bases: AbstractLogger, ResetInterface

A named channel that turns calls into records and offers them to handlers.

Handlers are consulted in stack order — the one pushed last first — and a record stops at the first handler that does not let it bubble. Processors run once per record, in order, and only once some handler has said it will handle it.

A logger is mutable: handlers and processors are pushed and popped while an application is being wired. The stacks are swapped as whole tuples, so a record being logged on another thread always sees a complete stack.

Build a channel called name.

Parameters:

  • name (str) –

    The channel every record from this logger carries.

  • handlers (Sequence[HandlerInterface], default: () ) –

    Consulted first to last.

  • processors (Sequence[ProcessorInterface], default: () ) –

    Run first to last on every record that is handled.

  • clock (ClockInterface | None, default: None ) –

    Where record times come from. By default, whichever clock is in force as each record is made — the system's, unless a test installed another with :meth:xtr_clock.Clock.using.

  • exception_handler (Callable[[Exception, LogRecord], None] | None, default: None ) –

    Called with any exception a handler or processor raises, instead of letting it propagate to the caller.

  • detect_cycles (bool, default: True ) –

    Abort records logged from inside the handling of another record, three levels deep, rather than recursing until the stack overflows.

name property

name: str

The channel this logger writes to.

handlers property

handlers: tuple[HandlerInterface, ...]

The handler stack, in the order records are offered to it.

processors property

processors: tuple[ProcessorInterface, ...]

The processors, in the order they run.

with_name

with_name(name: str) -> Logger

Return a logger for channel name sharing these handlers and processors.

The stacks are copied, the objects in them are not: pushing a handler onto one logger leaves the other as it was, while a handler both hold is the same handler.

push_handler

push_handler(handler: HandlerInterface) -> None

Put handler on top of the stack, where it is consulted first.

pop_handler

pop_handler() -> HandlerInterface

Remove and return the handler on top of the stack.

Raises:

set_handlers

set_handlers(handlers: Sequence[HandlerInterface]) -> None

Replace the whole stack; handlers[0] is consulted first.

push_processor

push_processor(processor: ProcessorInterface) -> None

Put processor in front of the others, where it runs first.

pop_processor

pop_processor() -> ProcessorInterface

Remove and return the processor that runs first.

Raises:

is_handling

is_handling(level: LevelLike) -> bool

Whether any handler would handle a record at level from this channel.

log

log(level: LevelLike, message: str, /, context: Context | None = None) -> None

Log message at level.

Raises:

  • InvalidLevelError –

    If level names no level.

add_record

add_record(level: LevelLike, message: str, context: Context | None = None, *, datetime: datetime | None = None) -> bool

Offer a record to the handlers; return whether any accepted it.

True means the record was processed and offered to at least one handler that accepted it per is_handling; False means every handler declined and the record went nowhere. What an accepting handler then did with the record is not reported: handle returns whether the record may bubble further, so a handler that queued the record and let it bubble and one that sampled it away are indistinguishable — both count as accepted here.

datetime overrides the clock, for records that happened earlier — one relayed from the standard library, say.

Raises:

  • InvalidLevelError –

    If level names no level.

close

close() -> None

Close every handler, flushing whatever they buffer.

reset async

reset() -> None

End a unit of work: reset every handler and processor that holds state.

Call it between the messages or requests of a long-running process, so a buffer or an activated fingers-crossed handler from one does not carry into the next.

LoggerFactory

LoggerFactory(config: LoggingConfig, *, services: Services | None = None, registry: ProcessorRegistry | None = None, clock: ClockInterface | None = None)

Bases: ResetInterface

Builds one logger per channel, sharing handlers between them.

Every handler in the configuration is built once, as the factory is made, so a missing service fails here rather than on the first record. Files and sockets still open lazily, on first write. A channel's logger gets every top-level handler whose channels accept it, highest priority first, and every processor not aimed elsewhere::

factory = LoggerFactory(CONFIG)
security = factory.logger("security")

With a capture section, the standard library's logging is taken over as the factory is made, and given back when it is closed.

Close the factory when the process ends — or use it as a context manager — so buffered and queued records are written.

Build every handler and processor config describes.

Parameters:

  • config (LoggingConfig) –

    The channels, handlers and processors.

  • services (Services | None, default: None ) –

    Objects the configuration names by id.

  • registry (ProcessorRegistry | None, default: None ) –

    Where :func:~xtr_logging.decorator.as_processor declarations are read from; the process-wide registry by default.

  • clock (ClockInterface | None, default: None ) –

    Where every logger reads the time.

Raises:

channels property

channels: tuple[str, ...]

Every channel a logger can be asked for.

capture property

capture: StdlibCapture | None

The standard-library capture, if the configuration asks for one.

logger

logger(channel: str | None = None) -> Logger

Return the logger for channel, or for the default channel.

The same logger is returned every time for the same channel.

Raises:

handler

handler(name: str) -> HandlerInterface

Return the handler configured as name — a test handler, say.

Raises:

set_verbosity

set_verbosity(verbosity: Verbosity) -> None

Set the verbosity of every console handler — what -v flags decide.

set_console_stream

set_console_stream(stream: IO[str] | None, *, colors: bool | None = None) -> None

Point every console handler at stream — a command's error output, typically.

None is standard error, resolved at write time. colors forces colours on or off; None colours only a real terminal.

reset async

reset() -> None

End a unit of work: reset every handler and processor that holds state.

close

close() -> None

Give the standard library its logging back, then close every handler.

Whatever is buffered or queued is written.

ContextVarsProcessor

ContextVarsProcessor(key: str | None = None)

Bases: ProcessorInterface

Copies whatever :func:~xtr_logging.log_context.bind_context bound into extra.

Fields bound for the current request or task — a request id, the user — ride along on every record without being passed to each logging call. With a key they are nested under extra[key]; without one they are merged in flat. An empty ambient context adds nothing.

Nest the bound values under key, or merge them in flat when None.

HostnameProcessor

Bases: ProcessorInterface

Adds extra["hostname"] — which machine a record came from.

Worth having once logs from several hosts are read together. The name is read from the operating system once and shared by every instance, since it does not change while the process runs.

IntrospectionProcessor

IntrospectionProcessor(level: LevelLike = Level.DEBUG, *, skip_module_prefixes: Sequence[str] = (), skip_frames: int = 0)

Bases: ProcessorInterface

Adds extra["file"], "line", "function" and "module".

Points at the code that logged, not at this library: frames inside xtr_logging — and any module prefix you name — are walked past, so the record shows the caller's own file and line. Skipping the walk below a level keeps its cost off the records a busy channel makes most of.

Introspect records at level or above.

Parameters:

  • level (LevelLike, default: DEBUG ) –

    Records below this are returned untouched.

  • skip_module_prefixes (Sequence[str], default: () ) –

    Module prefixes to walk past in addition to this library's own, for a wrapper between a caller and the logger.

  • skip_frames (int, default: 0 ) –

    Frames to step over after the first outside frame, for a caller that is itself one frame removed.

Raises:

  • InvalidLevelError –

    If level names no level.

PlaceholderProcessor

PlaceholderProcessor(date_format: str | None = None, *, remove_used_context_fields: bool = False)

Bases: ProcessorInterface

Replaces {key} in a message with context[key].

A caller writes logger.info("User {id} signed in", {"id": 7}) and the message becomes "User 7 signed in". Only placeholders with a matching context key are filled; the rest are left as written. A value is rendered the way a log reader expects — null, true, an object's own text, a nested value as array{...} — never by failing.

With remove_used_context_fields the keys that were substituted are dropped from the context, so they are not also printed beside the message.

Render values, dropping substituted keys when asked.

Parameters:

  • date_format (str | None, default: None ) –

    A :meth:~datetime.datetime.strftime format for datetime values; ISO 8601 when omitted.

  • remove_used_context_fields (bool, default: False ) –

    Drop each substituted key from the context once it is in the message.

ProcessIdProcessor

Bases: ProcessorInterface

Adds extra["process_id"] — the PID that made the record.

Read afresh for each record rather than cached, so a worker that forks reports the child's id, not the parent's.

ProcessorInterface

Bases: Protocol

Takes a record and returns it, usually with something added to extra.

Any callable of that shape qualifies, so a plain function is a processor. Records are immutable: return a new one, via :meth:~xtr_logging.log_record.LogRecord.with_extra or :func:dataclasses.replace.

A processor attached to a logger runs once per record, and only if some handler is going to handle it — so an expensive one costs nothing for a record every handler would have dropped.

ProcessorRegistry

ProcessorRegistry()

Holds declared processors until a factory attaches them.

:func:~xtr_logging.decorator.as_processor writes to the process-wide one by default, which is what lets a module declare a processor without importing the factory. Pass a registry of your own to keep two applications — or two tests — apart.

Class declarations stay classes until :attr:descriptors is read for the first time, so importing a module that decorates a class costs no instantiation. A container-provided processor for a class is passed to :meth:bind_class before that first read, and the registry returns it instead of building one itself.

Start empty.

descriptors property

descriptors: tuple[ProcessorDescriptor, ...]

Every declared processor, in declaration order.

A class declaration is materialised on first read — from the binding set by :meth:bind_class if any, else by calling the class with no arguments — and cached for subsequent reads.

register

register(descriptor: ProcessorDescriptor) -> None

Declare descriptor — a ready-built processor instance.

Declaring the same processor the same way again adds nothing, so a module decorating it twice does not run it twice.

register_class

register_class(cls: type[ProcessorInterface], /, *, channel: str | None = None, handler: str | None = None, priority: int = 0) -> None

Declare a processor class; it is instantiated lazily on first read.

Declaring the same class the same way again adds nothing.

bind_class

bind_class(cls: type[ProcessorInterface], instance: ProcessorInterface) -> None

Provide instance for cls, instead of instantiating it here.

clear

clear() -> None

Forget every declared processor.

RedactingProcessor

RedactingProcessor(keys: str | None = DEFAULT_KEY_PATTERN, values: Sequence[str] = (), *, mask: str = DEFAULT_MASK)

Bases: ProcessorInterface

Replaces secrets in a record's message, context and extra before anything writes them.

A value is masked when its key matches keys — password, api_key, authorization and the like by default, matched anywhere in the key and without regard to case — so a whole secret never reaches a file, a terminal or a third-party sink. Matching is recursive: a key deep in a nested mapping, or inside a list of them, is masked too, and a matching key masks its whole value, however nested. A key that is not a string cannot match, but its value is still scanned.

values adds patterns matched against the message and against string values wherever they sit; each match is replaced with the mask, so a card number or a bearer token pasted into an otherwise innocent message is caught by shape rather than by the key above it. Bytes and bytearrays are decoded as UTF-8 with errors="replace" for scanning — returned untouched when nothing matches, as the redacted text re-encoded otherwise; an untouched bytearray stays a bytearray. Tuples and sets come back as lists, like lists do. A bytes key is decoded the same way to be matched. Keys go through values as well, so a secret a caller used as the name of an entry is masked rather than written out whole; a key that is not text cannot be scanned and comes back as it is.

What a formatter would otherwise turn into text behind this processor's back is redacted too. An exception — the logged exception and any other — has its message, notes, cause and context run through values, and is masked whole when its message matches keys; it comes back as a copy of the same class with the original traceback, or, when it cannot be copied, as a plain Exception carrying its class name and redacted text. A dataclass is redacted field by field and comes back as {class name: fields}, the shape a formatter writes it in. Any other object is matched against values by the text a formatter would write for it, and replaced by that text redacted when anything matches.

Mask by key and by value shape.

Parameters:

  • keys (str | None, default: DEFAULT_KEY_PATTERN ) –

    A regular expression matched, case-insensitively, against each key; the value of a key it matches is masked. None masks by value only.

  • values (Sequence[str], default: () ) –

    Regular expressions matched against string values anywhere; each match is replaced with mask.

  • mask (str, default: DEFAULT_MASK ) –

    What a masked value, or a matched span, is replaced with.

TagProcessor

TagProcessor(tags: Sequence[str] = ())

Bases: ProcessorInterface

Adds extra["tags"] — labels shared by every record it processes.

Attach one to a channel to mark where its records came from — "billing", "deploy" — so they can be filtered downstream without parsing the message. The tags may be changed while the application is being wired.

Start with tags.

add_tags

add_tags(*tags: str) -> None

Add tags to those already set.

set_tags

set_tags(tags: Sequence[str]) -> None

Replace the tags with tags.

UidProcessor

UidProcessor(length: int = 7)

Bases: ProcessorInterface, ResetInterface

Adds extra["uid"] — one id tying together the records of a request.

Inside a unit of work the id lives on the unit, so concurrent requests each get their own stable id from the one shared processor. Outside a unit the id lives on the instance, as before. Either way every record carries the same id until :meth:reset mints a fresh one for the next unit of work.

Generate ids of length hexadecimal characters.

Raises:

uid property

uid: str

The id every record carries until the next :meth:reset.

reset async

reset() -> None

Mint a fresh id for the next unit of work.

Inside a unit the id is replaced on the unit's holder in place, so the change follows the unit's context even into a synchronous callee run in a copied context.

Verbosity

Bases: IntEnum

How much a console command was told to say.

A command run with more -v flags shows more, and these are the thresholds a :class:~xtr_logging.handler.console_handler.ConsoleHandler maps to log levels. The values are powers of two, leaving room for a level in between.

from_count classmethod

from_count(verbose: int, *, quiet: bool = False, silent: bool = False) -> Verbosity

Read the verbosity a count of -v flags asks for.

--silent wins over -q, which silences a command however often -v was also given.

bind_context

bind_context(values: Context) -> None

Add values to the ambient context, overwriting any keys they share.

bound_context

bound_context(values: Context) -> Generator[None]

Bind values for the duration of the block, then restore what was there.

Nesting merges: inside the block the ambient context is what was bound before plus values, with values winning a clash. The previous state is put back on the way out whether the block returns or raises. A block exited in another context than it was entered in puts nothing back there: that context never held what the block bound.

clear_context

clear_context() -> None

Drop the bound values: in a unit of work, the unit's own; outside one, all of them.

Inside a unit what was bound outside any unit lasts: a request clearing what it bound must not take away what the process bound for good.

current_context

current_context() -> Context

The values bound in this thread or task, as a read-only mapping.

What was bound in a unit of work other than the one open here — or in one that is over — is left out: it was bound for that unit.

unbind_context

unbind_context(*keys: str) -> None

Remove keys from the ambient context; keys not bound are ignored.

Inside a unit of work a key bound outside any unit is set aside for that unit only, and is back once the unit is over.

begin_unit

begin_unit() -> None

Open a fresh unit of work in the current context.

A unit this context began and never ended is ended first, so a caller that forgot :func:end_unit cannot leak one unit's state into the next. A unit the context only carries is let go of the way :func:end_unit lets go of one. The new unit is open even when ending the earlier one raised.

Raises:

  • ExceptionGroup –

    If one or more end callbacks of the earlier unit raised.

end_unit

end_unit() -> None

Close the unit this context began, running every end callback, then clear the context.

Callbacks run in registration order. Every one runs even if an earlier one raised; the failures are then raised together as an :class:ExceptionGroup. Does nothing when no unit is open. A unit work is still queued for closes — and its callbacks run — once that work releases it; see :func:hold_unit.

A unit the context only carries — begun in the context this one was copied from — is let go of rather than ended: the context is cleared and nothing else, its callbacks being for whoever began it. Once that unit is closed it hands out no state, so nothing this context logs can be stranded in it.

Raises:

in_unit

in_unit() -> bool

Whether a unit of work is open in the current context.

unit_state

unit_state(owner: object, factory: Callable[[], T], on_end: Callable[[T], object] | None = None) -> T | None

Return owner's state in the unit carried here, or None outside one.

The state is created with factory() the first time owner asks in a unit and returned unchanged on every later call, so an owner keeps one mutable object per unit and mutates it in place. When given, on_end is registered the moment the state is created and called with that state when the unit closes. A closed unit — one a context still carries once it is over — is no unit: it hands out nothing, and takes no callback it would never run.

Parameters:

  • owner (object) –

    The object the state belongs to; distinct owners keep distinct state within one unit.

  • factory (Callable[[], T]) –

    Builds the state on first use in a unit.

  • on_end (Callable[[T], object] | None, default: None ) –

    Called with the state when the unit closes, registered once.

Returns:

  • T | None –

    The owner's state for the unit, or None if none is carried here or

  • T | None –

    it is closed.

default_processor_registry

default_processor_registry() -> ProcessorRegistry

Return the process-wide registry :func:as_processor declares into.