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 ¶
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'schannelslist 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
RedactingProcessorConfigthere 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
¶
Every declared channel: the default, the listed, then those named by handlers.
nested_handlers
property
¶
Handlers kept off every channel's stack: those named by another, or marked nested.
top_level_handlers
property
¶
Handlers on the channel stacks, highest priority first, ties in declaration order.
from_mapping
classmethod
¶
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:
-
InvalidConfigurationError–If the data does not fit, naming where.
-
UnknownHandlerError–If a wrapper or processor names a missing handler.
-
CircularHandlerReferenceError–If wrappers nest each other in a loop.
-
UnknownChannelError–If a processor targets a missing channel.
with_channels ¶
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 ¶
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:
-
handlers(Mapping[str, HandlerInterface]) –For
type: servicehandlers. -
formatters(Mapping[str, FormatterInterface]) –For a handler's
formattergiven as a string. -
processors(Mapping[str, ProcessorInterface]) –For
type: serviceprocessors. -
activation_strategies(Mapping[str, ActivationStrategyInterface]) –For a fingers-crossed handler's
activation_strategy. -
error_handlers(Mapping[str, Callable[[Exception, LogRecord], None]]) –For a queue handler's
on_errorgiven as a string.
CaptureConflictError ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
Bases: LoggingError
A processor targets a handler that runs no processors of its own.
Record the handler that cannot take a processor.
UnknownChannelError ¶
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 ¶
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 ¶
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.strftimeformat;%H:%M:%Swhen 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 ¶
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_batchyields 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
contextorextraout 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.strftimeformat 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_batch ¶
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_FORMATwhen omitted. -
date_format(str | None, default:None) –A :meth:
~datetime.datetime.strftimeformat; 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.
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.strftimeformat 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.
AbstractHandler ¶
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
levelnames no level.
set_level ¶
Handle records at level or above from now on.
Raises:
-
InvalidLevelError–If
levelnames no level.
is_handling ¶
Whether record is at this handler's level or above.
handle
abstractmethod
¶
Handle record; return True to stop it bubbling.
reset
async
¶
Forget nothing; handlers holding per-unit-of-work state override this.
AbstractProcessingHandler ¶
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
¶
The formatter in use, built from :meth:default_formatter on first use.
handle ¶
Process, format and write record if it is at this handler's level.
default_formatter ¶
The formatter used until another is set: one line of text per record.
write
abstractmethod
¶
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 ¶
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;
0means no limit. Bounded at10_000by default. Past it, the oldest record is dropped unlessflush_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
levelnames no level.
handle ¶
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.
reset
async
¶
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 ¶
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.SILENTprints nothing, whatever it maps to. -
bubble(bool, default:True) –Let a handled record reach later handlers.
set_verbosity ¶
Print at the level verbosity maps to from now on.
set_stream ¶
is_handling ¶
Whether record is at the level, and the command is not silent.
write ¶
Write formatted to the stream, or to standard error.
default_formatter ¶
A short console line, coloured as :meth:set_stream said, or on a real terminal.
DebugHandler ¶
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
levelnames no level.
handle ¶
Keep record in the open unit when it began recording, and let it bubble on.
begin ¶
Start keeping the open unit's records, from none; do nothing outside a unit.
get_logs ¶
Return the records of the open unit, oldest first; none outside a unit.
count_errors ¶
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;
0holds them all. -
flush_on_overflow(bool, default:False) –Forward the held records when
buffer_limitis 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_levelnames 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 ¶
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_levelnames no level.
is_handler_activated ¶
Whether record is at action_level or above.
FallbackGroupHandler ¶
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.
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
¶
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 ¶
Whether record's level is one this handler accepts.
handle ¶
Forward record if its level is accepted, after this handler's processors.
handle_batch ¶
Forward the accepted records of records as one batch, after its own processors.
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 onWARNINGand above. -
buffer_size(int, default:10000) –The most records to keep before the oldest are dropped;
0keeps everything until activation. Bounded at10_000by 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;
Noneflushes nothing in that case.
Raises:
-
InvalidLevelError–If a level argument names no level.
is_handling ¶
Always True: everything is buffered until the buffer is released.
handle ¶
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 ¶
Offer each record in turn, as a logger would one by one.
reset
async
¶
Flush the passthru floor, reset processors, and reset the wrapped handler.
FormattableHandlerInterface ¶
GroupHandler ¶
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.
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 ¶
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; return True to stop it reaching later handlers.
handle_batch ¶
Handle several records at once, as a buffer flushes them.
NullHandler ¶
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 ¶
Discard record; stop it if it is at this handler's level.
ProcessableHandlerInterface ¶
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:
handleblocks to apply backpressure;0means an unbounded queue that never blocks. Bounded at10_000by 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 ¶
Whether the wrapped handler would handle record.
handle ¶
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.
flush ¶
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
¶
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.
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.strftimeformat for the date. -
filename_format(str, default:'{filename}-{date}') –A template with
{filename}and{date}. -
file_permission(int | None, default:None) –The mode to
chmodeach 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_formatlacks{date}ordate_formatholds no strftime directive, or renders a path separator that would scatter the dated files across directories. -
InvalidLevelError–If
levelnames no level.
write ¶
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;
1keeps everything,10keeps 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.Randomby default.
Raises:
-
InvalidOptionError–If
factoris less than1.
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
encodingcannot represent, as :func:opentakes it; escaped by default, so a log call never fails over one character.
Raises:
-
InvalidLevelError–If
levelnames no level.
stream
property
¶
The open stream, or None before the first write or after :meth:close.
write ¶
Write formatted to the stream, opening a configured path if need be.
handle_batch ¶
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.
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
sockettype; 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
facilitynames no known facility. -
InvalidLevelError–If
levelnames no level.
TestHandler ¶
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.
has_record ¶
Whether a record at level has exactly message, and context if given.
has_record_that_contains ¶
Whether a record at level has a message containing fragment.
has_record_that_matches ¶
Whether a record at level has a message matching pattern anywhere.
has_record_that_passes ¶
Whether predicate holds for some record at exactly level.
WhatFailureGroupHandler ¶
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.
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
contextso a processor can never overwrite something the caller said.
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.
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.
handlers
property
¶
The handler stack, in the order records are offered to it.
processors
property
¶
The processors, in the order they run.
with_name ¶
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 ¶
Put handler on top of the stack, where it is consulted first.
pop_handler ¶
set_handlers ¶
Replace the whole stack; handlers[0] is consulted first.
push_processor ¶
Put processor in front of the others, where it runs first.
pop_processor ¶
Remove and return the processor that runs first.
Raises:
-
EmptyStackError–If there are no processors.
is_handling ¶
Whether any handler would handle a record at level from this channel.
log ¶
Log message at level.
Raises:
-
InvalidLevelError–If
levelnames 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
levelnames no level.
reset
async
¶
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_processordeclarations are read from; the process-wide registry by default. -
clock(ClockInterface | None, default:None) –Where every logger reads the time.
Raises:
-
UnknownServiceError–If the configuration names a missing service.
-
UnknownChannelError–If a declared processor targets a missing channel.
-
UnknownHandlerError–If a declared processor targets a missing handler.
-
NotProcessableHandlerError–If a processor targets a handler that runs none.
capture
property
¶
The standard-library capture, if the configuration asks for one.
logger ¶
Return the logger for channel, or for the default channel.
The same logger is returned every time for the same channel.
Raises:
-
UnknownChannelError–If
channelis not declared.
handler ¶
Return the handler configured as name — a test handler, say.
Raises:
-
UnknownHandlerError–If no handler has that name.
set_verbosity ¶
Set the verbosity of every console handler — what -v flags decide.
set_console_stream ¶
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
¶
End a unit of work: reset every handler and processor that holds state.
close ¶
Give the standard library its logging back, then close every handler.
Whatever is buffered or queued is written.
ContextVarsProcessor ¶
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
levelnames no level.
PlaceholderProcessor ¶
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.strftimeformat 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 ¶
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
¶
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 ¶
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 ¶
Provide instance for cls, instead of instantiating it here.
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.
Nonemasks 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 ¶
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.
UidProcessor ¶
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:
-
InvalidOptionError–If
lengthis not between 1 and 32.
reset
async
¶
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
¶
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 ¶
Add values to the ambient context, overwriting any keys they share.
bound_context ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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:
-
ExceptionGroup–If one or more end callbacks raised.
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
Noneif none is carried here or -
T | None–it is closed.
default_processor_registry ¶
Return the process-wide registry :func:as_processor declares into.