lenskit.logging.tracing#

Extended logger providing TRACE support.

Functions

activate_tracing([active])

Mark tracing as active (or inactive).

get_tracer(logger, **initial_values)

Get a tracer for efficient low-level tracing of computations.

lenskit_filtering_logger(level)

No-op filtering logger.

trace(logger, *args, **kwargs)

Emit a trace-level message, if LensKit tracing is enabled.

tracing_active()

Query whether tracing is active.

Classes

ActiveTracer(logger)

Active tracer that actually sends trace messages.

Tracer(logger)

Logger-like thing that is only for TRACE-level events.

TracingLogger(logger, processors, context)

Class for LensKit loggers with trace-level logging support.
lenskit.logging.tracing.tracing_active()#

Query whether tracing is active.

Return type:

bool

lenskit.logging.tracing.activate_tracing(active=True)#

Mark tracing as active (or inactive).

Global tracing state is just used to short-cut tracing. This method should only be called from LoggingConfig.

Parameters:

active (bool | Literal['debug']) – The global tracing state. If "debug", trace messages are emitted at DEBUG level.

Return type:

None

lenskit.logging.tracing.trace(logger, *args, **kwargs)#

Emit a trace-level message, if LensKit tracing is enabled. Trace-level messages are more fine-grained than debug-level messages, and you usually don’t want them.

This function does not work on the lazy proxies returned by get_logger() and similar — it only works on bound loggers.

Stability:
Caller (see Stability Levels).
Parameters:
lenskit.logging.tracing.get_tracer(logger, **initial_values)#

Get a tracer for efficient low-level tracing of computations.

Stability:

Experimental

Parameters:
class lenskit.logging.tracing.Tracer(logger)#

Bases: object

Logger-like thing that is only for TRACE-level events.

This class is designed to support structured tracing without the overhead of creating and binding new loggers. It is also imperative, rather than functional, so we create fewer objects and so it is a little more ergonomic for common tracing flows.

Note

Don’t create instances of this class directly — use get_tracer() to create a tracer.

Stability:

Experimental

Parameters:

logger (BoundLogger)

add_bindings(**new_values)#

Bind new data in the keys.

Note

Unlike structlog.Logger.bind(), this method is **imperative*: it updates the tracer in-place instead of returning a new tracer. If you need a new, disconnected tracer, use split().

Parameters:

new_values (Any)

Return type:

None

remove_bindings(*keys)#

Unbind keys in the tracer.

Note

Unlike structlog.Logger.bind(), this method is **imperative*: it updates the tracer in-place instead of returning a new tracer. If you need a new, disconnected tracer, use split().

Parameters:

keys (str)

Return type:

None

reset()#

Reset this tracer’s underlying logger to the original logger.

Return type:

None

trace(event, *args, **bindings)#

Emit a TRACE-level event.

Parameters:
Return type:

None

class lenskit.logging.tracing.ActiveTracer(logger)#

Bases: Tracer

Active tracer that actually sends trace messages.

Parameters:

logger (BoundLogger)

add_bindings(**new_values)#

Bind new data in the keys.

Note

Unlike structlog.Logger.bind(), this method is **imperative*: it updates the tracer in-place instead of returning a new tracer. If you need a new, disconnected tracer, use split().

Parameters:

new_values (Any)

Return type:

None

remove_bindings(*keys)#

Unbind keys in the tracer.

Note

Unlike structlog.Logger.bind(), this method is **imperative*: it updates the tracer in-place instead of returning a new tracer. If you need a new, disconnected tracer, use split().

Parameters:

keys (str)

Return type:

None

reset()#

Reset this tracer’s underlying logger to the original logger.

Return type:

None

trace(event, *args, **bindings)#

Emit a TRACE-level event.

Parameters:
class lenskit.logging.tracing.TracingLogger(logger, processors, context)#

Bases: BoundLogger

Class for LensKit loggers with trace-level logging support.

Code should not directly use the tracing logger — it should use the trace() function that intelligently checks the logger.

Parameters:

  • logger (WrappedLogger)

  • processors (Iterable[Processor])

  • context (Context)

bind(**new_values)#

Return a new logger with new_values added to the existing ones.

Parameters:

new_values (Any)

Return type:

TracingLogger

new(**new_values)#

Clear context and binds initial_values using bind.

Only necessary with dict implementations that keep global state like those wrapped by structlog.threadlocal.wrap_dict when threads are reused.

Parameters:

new_values (Any)

Return type:

TracingLogger

lenskit.logging.tracing.lenskit_filtering_logger(level)#

No-op filtering logger.

Parameters:

level (int)