redsun.log¶

redsun logs everything to the redsun logger. Usage is in Configure logging.

Symbol	What it does
`set_level`	sets the level of the `redsun` logger
`add_handler`	sends the logger's records to one more handler
`remove_handler`	stops sending records to a handler
`Loggable`	gives a component a `logger` that names the component in each record
`BufferHandler`	keeps the most recent records of the session in memory
`log_buffer`	returns the `BufferHandler` installed on the logger
`SessionFileHandler`	writes the records of one run of a session to a rotated file
`session_log`	returns the `SessionFileHandler` installed on the logger, or on a service's, if any
`service_of`	names the service a record came from

The built-in LogView shows these records in the application.

Functions¶

set_level ¶

set_level(level: int | str) -> None

Set the level of the redsun logger.

Level names are case-insensitive.

Raises:

Type	Description
`ValueError`	If a name names no level.

add_handler ¶

add_handler(
    handler: Handler, service: str | None = None
) -> None

Send the redsun logger's records to handler as well.

With a service, only that service's records reach handler. A handler without a formatter gets the shared one, so records read the same everywhere.

remove_handler ¶

remove_handler(
    handler: Handler, service: str | None = None
) -> None

Stop sending the records add_handler sent to handler.

A handler that is not installed is left alone.

log_buffer ¶

log_buffer() -> BufferHandler

Return the buffer holding this session's log records.

Raises:

Type	Description
`RuntimeError`	If the logging configuration no longer carries a buffer.

session_log ¶

session_log(
    service: str | None = None,
) -> SessionFileHandler | None

Return the handler writing this run's log file, if a session opened one.

With a service, the handler writing that service's file.

service_of ¶

service_of(record: LogRecord) -> str | None

Return the name of the service record came from, None for the application.

Logging from a component¶

Loggable ¶

Mixin giving instances a logger that names them in each record.

logger `cached` `property` ¶

logger: LoggerAdapter[Logger]

Logger naming this instance in each record.

Session records¶

BufferHandler ¶

BufferHandler(
    capacity: int = APPLICATION_CAPACITY,
    service_capacity: int = SERVICE_CAPACITY,
)

Bases: Handler

Retain the most recent log records, and announce each one as it arrives.

A consumer built later in the session can still show earlier records. Application records and each service's records are kept apart, each dropping its oldest when full, so a noisy service drops only its own.

Parameters:

Name	Type	Description	Default
`capacity`	`int`	How many application records to retain.	`APPLICATION_CAPACITY`
`service_capacity`	`int`	How many records of each service to retain.	`SERVICE_CAPACITY`

capacity `property` ¶

capacity: int

How many application records the buffer retains.

service_capacity `property` ¶

service_capacity: int

How many records of each service the buffer retains.

records `property` ¶

records: tuple[LogRecord, ...]

The retained application records, oldest first.

services `property` ¶

services: tuple[str, ...]

The services a record has come from, in the order they first did.

service_records ¶

service_records(
    service: str | None = None,
) -> tuple[logging.LogRecord, ...]

Return one service's retained records, or every service's, oldest first.

emit ¶

emit(record: LogRecord) -> None

Retain record with the records of its source, and announce it.

What is retained is a copy holding the message and the traceback as text, so the record's arguments and exception are not kept alive. A record whose arguments do not fit its message is reported through handleError and not retained.

clear ¶

clear() -> None

Drop every retained record.

SessionFileHandler ¶

SessionFileHandler(
    session: str,
    service: str | None = None,
    run: str | None = None,
    *,
    root: Path | None = None,
)

Bases: RotatingFileHandler

Write the records of one run of a session to a file of its own.

The file is under logs in the session's root, in a folder named after the session, then in app for the application or services for a service, and named after the run: its start time and process. It rotates at LOG_MAX_BYTES, keeping LOG_BACKUPS older files. move carries the run's files to another root and keeps writing there.

The application's file, <run>.log, takes no service records, and opening it deletes the files of all but the session's LOG_RUNS_KEPT most recent runs. A service's file, <run>.<service>.log, belongs to run, is installed with add_handler(handler, service), and is created when the service first logs.

Parameters:

Name	Type	Description	Default
`session`	`str`	Name of the session.	required
`service`	`str \| None`	The service whose records the file holds, `None` for the application.	`None`
`run`	`str \| None`	The run, as the application handler's `run`. `None` starts a new run.	`None`
`root`	`Path \| None`	Root the session writes under, as the path provider's `base_dir`. `None` is the user data directory.	`None`

root `property` ¶

root: Path

Root the run's files are under.

files `property` ¶

files: list[Path]

The files of this run, oldest records first.

shouldRollover ¶

shouldRollover(record: LogRecord) -> bool

Whether the file has reached LOG_MAX_BYTES, by its size alone.

The file is always one this handler made, so it skips the base class's check that it is a regular file, which costs a file system call per record. A file may pass the limit by one record.

move ¶

move(root: Path) -> None

Carry the run's files under root and keep writing there.

Nothing happens when root is the current one.