lenskit.logging

Logging, progress, and resource records.

Submodules

multiprocess	Multiprocess logging support for Ray integration. Most code doesn't need to
progress
tasks	Abstraction for recording tasks.

Attributes

console

Classes

LoggingConfig	Configuration for LensKit logging.
ResourceMeasurement	Single measurement of resources. Two measurements can be subtracted to
Stopwatch	Timer class for recording elapsed wall time in operations.
Tracer	Logger-like thing that is only for TRACE-level events.

Functions

basic_logging([level])	Simple one-function logging configuration for simple command lines.
notebook_logging([level])	Simple one-function logging configuration for notebooks and similar.
stdout_console()	Get a console attached to stdout.
friendly_duration(elapsed)	Short, human-friendly representation of a duration.
get_logger(name, *[, remove_private])	Get a logger. This works like structlog.stdlib.get_logger(), except
get_tracer(logger, **initial_values)	Get a tracer for efficient low-level tracing of computations.
trace(logger, *args, **kwargs)	Emit a trace-level message, if LensKit tracing is enabled. Trace-level

Package Contents

class lenskit.logging.LoggingConfig

Configuration for LensKit logging.

This class is intended as a convenience for LensKit applications to set up a useful logging and progress reporting configuration; if unconfigured, LensKit will emit its logging messages directly to structlog and/or logging, which you can configure in any way you wish.

Stability:

Caller (see Stability Levels).

level: int = 20

stream: Literal['full', 'simple', 'json'] = 'full'

progress_backend: Literal['notebook', 'rich'] | None = None

file: pathlib.Path | None = None

file_level: int | None = None

file_format: LogFormat = 'json'

property effective_level: int

Return type:

int

set_stream_mode(mode)

Configure the standard error stream mode.

Parameters:

mode (Literal['full', 'simple', 'json'])

set_verbose(verbose=True)

Enable verbose logging.

Note

It is better to only call this method if your application’s verbose option is provided, rather than passing your verbose option to it, to allow the LK_LOG_LEVEL environment variable to apply in the absence of a configuration option.

Parameters:

verbose (bool | int) – The level of verbosity. Values of True or 1 turn on DEBUG-level logs, and 2 or greater turns on tracing.

set_log_file(path, level=None, format='json')

Configure a log file.

Parameters:

• path (os.PathLike[str])

• level (int | None)

• format (LogFormat)

apply()

Apply the configuration.

lenskit.logging.basic_logging(level=logging.INFO)

Simple one-function logging configuration for simple command lines.

Stability:

Caller (see Stability Levels).

Parameters:

level (int)

lenskit.logging.notebook_logging(level=logging.INFO)

Simple one-function logging configuration for notebooks and similar.

Stability:

Caller (see Stability Levels).

Parameters:

level (int)

lenskit.logging.console

lenskit.logging.stdout_console()

Get a console attached to stdout.

lenskit.logging.friendly_duration(elapsed)

Short, human-friendly representation of a duration.

Parameters:

elapsed (float | datetime.timedelta)

lenskit.logging.get_logger(name, *, remove_private=True, **init_als)

Get a logger. This works like structlog.stdlib.get_logger(), except the returned proxy logger is quiet (only WARN and higher messages) if structlog has not been configured. LensKit code should use this instead of obtaining loggers from Structlog directly.

It also suppresses private module name components of the logger name, so e.g. lenskit.pipeline._impl becomes ``lenskit.pipeline`.

Params:

name:

The logger name.

remove_private:

Set to False to keep private module components of the logger name instead of removing them.

init_vals:

Initial values to bind into the logger when crated.

Returns:

A lazy proxy logger. The returned logger is type-compatible with structlib.stdlib.BoundLogger, but is actually an instance of an internal proxy that provies more sensible defaults and handles LensKit’s TRACE-level logging support.

Parameters:

• name (str)

• remove_private (bool)

• init_als (Any)

Return type:

structlog.stdlib.BoundLogger

class lenskit.logging.ResourceMeasurement

Single measurement of resources. Two measurements can be subtracted to compute the time resources consumed in an interval (memory resources are left unchanged).

Stability:

Internal (see Stability Levels).

wall_time: float

perf_time: float

user_time: float

system_time: float

max_rss: int | None = None

Maximum RSS usage (in bytes).

max_gpu: int | None = None

classmethod current()

Get the current resource measurements.

property cpu_time: float

Total CPU time (user + system).

Return type:

float

__sub__(other)

Parameters:

other (ResourceMeasurement)

class lenskit.logging.Stopwatch(start=True)

Timer class for recording elapsed wall time in operations.

acc_time: float | None = None

start_time: float | None = None

stop_time: float | None = None

start()

stop()

elapsed(*, accumulated=True)

Get the elapsed time.

Return type:

float

measure(accumulate=False)

Context manager to measure an item, optionally accumulating its time.

Parameters:

accumulate (bool)

__str__()

__repr__()

class lenskit.logging.Tracer(logger)

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 (structlog.stdlib.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:

• event (str)

• args (Any)

• bindings (Any)

Return type:

None

lenskit.logging.get_tracer(logger, **initial_values)

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

Stability:

Experimental

Parameters:

• logger (str | structlog.stdlib.BoundLogger)

• initial_values (Any)

lenskit.logging.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:

• logger (structlog.stdlib.BoundLogger)

• args (Any)

• kwargs (Any)

Exported Aliases

class lenskit.logging.Progress

Re-exported alias for lenskit.logging.progress.Progress.

lenskit.logging.item_progress()

Re-exported alias for lenskit.logging.progress.item_progress().

lenskit.logging.set_progress_impl()

Re-exported alias for lenskit.logging.progress.set_progress_impl().

class lenskit.logging.Task

Re-exported alias for lenskit.logging.tasks.Task.