Logging

Logging related utils

File: klea_utils/plogging.py

Copyright 2026 Ankur Sinha Author: Ankur Sinha <sanjay DOT ankur AT gmail DOT com>

klea_utils.plogging.KLEA_LOG_NAMESPACES = ('klea_utils', 'klea_rag', 'klea_agent', 'neuroml_mcp')

Klea logger namespaces that are turned up to DEBUG by setup_root_logger. Everything else (third-party libraries) inherits the root logger’s INFO level, so their DEBUG output is filtered at the source without having to enumerate them.

class klea_utils.plogging.LoggerInfoFilter(name='')[source]

Bases: Filter

Allow only INFO messages

filter(record)[source]

Determine if the specified record is to be logged.

Returns True if the record should be logged, or False otherwise. If deemed appropriate, the record may be modified in-place.

class klea_utils.plogging.LoggerNotInfoFilter(name='')[source]

Bases: Filter

Allow only non INFO messages

filter(record)[source]

Determine if the specified record is to be logged.

Returns True if the record should be logged, or False otherwise. If deemed appropriate, the record may be modified in-place.

klea_utils.plogging.mask_sensitive(data: dict[str, Any], sensitive_keys: set[str] | None = None) → dict[str, Any][source]

Return a copy with sensitive values masked for logging.

Shows only the last 4 characters of each value to prevent secrets (API keys, tokens) from appearing in plaintext in log output.

Parameters:

  • data – The dict to sanitize.

  • sensitive_keys – Keys whose values should be masked. Defaults to {"api_key"}.

Returns:

New dict with masked values.

klea_utils.plogging.setup_root_logger(app_name: str, stderr_level: int = 10, log_dir: str | Path | None = None) → Logger[source]

Configure the root logger once per process.

Idempotent: if the root logger already has handlers, this is a no-op and the existing configuration is returned unchanged.

Adds, on the root logger:

  • a stdout handler for INFO messages (simple format)

  • a stderr handler for all other levels at stderr_level (format includes the function name)

  • an optional RotatingFileHandler at {log_dir}/{app_name}.log logging all levels at DEBUG when log_dir is provided

The root logger is set to INFO. The Klea logger namespaces (see KLEA_LOG_NAMESPACES) and the application logger (app_name) are raised to DEBUG so our own logs are captured in full. Because module loggers propagate to the root logger by default, a single call from each application entry point routes all Klea logs (library modules, graph nodes, API routers) through the same console and file handlers. Third-party libraries inherit the root’s INFO level, so their DEBUG output is filtered at the source without enumerating them.

Parameters:

  • app_name – Application name, used as the log file name to keep per-app logs separate (e.g. "klea-rag").

  • stderr_level – Level for the stderr handler (default DEBUG)

  • log_dir – Directory for the log file. None disables file logging.

Returns:

The configured root logger