Stacks in Logbook¶
Logbook keeps three stacks internally currently:
- one for the
Handlers: each handler is handled from stack top to bottom. When a record was handled it depends on the
bubbleflag of the handler if it should still be processed by the next handler on the stack.
- one for the
Processors: each processor in the stack is applied on a record before the log record is handled by the handler.
- one for the
Flags: this stack manages simple flags such as how errors during logging should be processed or if stackframe introspection should be used etc.
General Stack Management¶
Commonly stacked objects are used with a context manager (with statement):
with context_object.threadbound(): # this is managed for this thread only ... with context_object.applicationbound(): # this is managed for all applications ...
Alternatively you can also use try/finally:
context_object.push_thread() try: # this is managed for this thread only ... finally: context_object.pop_thread() context_object.push_application() try: # this is managed for all applications ... finally: context_object.pop_application()
It’s very important that you will always pop from the stack again unless you really want the change to last until the application closes down, which probably is not the case.
If you want to push and pop multiple stacked objects at the same time, you
can use the
setup = NestedSetup([stacked_object1, stacked_object2]) with setup.threadbound(): # both objects are now bound to the thread's stack ...
Sometimes a stacked object can be passed to one of the functions or
methods in Logbook. If any stacked object can be passed, this is usually
called the setup. This is for example the case when you specify a
handler or processor for things like the
Handlers use the features of the stack the most because not only do they
stack, but they also specify how stack handling is supposed to work. Each
handler can decide if it wants to process the record, and then it has a
bubble flag) which specifies if the
next handler in the chain is supposed to get this record passed to.
If a handler is bubbling it will give the record to the next handler,
even if it was properly handled. If it’s not, it will stop promoting
handlers further down the chain. Additionally there are so-called
“blackhole” handlers (
NullHandler) which stop processing
at any case when they are reached. If you push a blackhole handler on top
of an existing infrastructure you can build up a separate one without
A processor can inject additional information into a log record when the record is handled. Processors are called once at least one log handler is interested in handling the record. Before that happens, no processing takes place.
Here an example processor that injects the current working directory into the extra attribute of the record:
import os def inject_cwd(record): record.extra['cwd'] = os.getcwd() with Processor(inject_cwd): # all logging calls inside this block in this thread will now # have the current working directory information attached. ...
The last pillar of logbook is the flags stack. This stack can be used to override settings of the logging system. Currently this can be used to change the behavior of logbook in case an exception during log handling happens (for instance if a log record is supposed to be delivered to the filesystem but it ran out of available space). Additionally there is a flag that disables frame introspection which can result in a speedup on JIT compiled Python interpreters.
Here an example of a silenced error reporting:
with Flags(errors='silent'): # errors are now silent for this block ...