bioptimus.observability.logging

Structured JSON logging for the SDK. Provides a JSON log formatter, a helper for emitting structured events with a machine-readable error code and arbitrary fields, and a configure_logging entry point for explicit setup. Logging works with zero setup: importing the package has no side effects, but the first emitted event auto-installs a default file handler (see default_log_file) so a durable record always exists; the console stays silent unless configure_logging(console=True) (or an explicit stream) is passed, and records always propagate to the application’s own logging hierarchy. Call configure_logging to override the destination, level, or anonymization, or set BIOPTIMUS_LOG_FILE to redirect the file. Setting BIOPTIMUS_LOG_FILE to an empty string disables the SDK’s own file sink and auto-init — it does not silence logging, since records still propagate to any handlers the host application (or configure_logging(console=True)) has installed. Each emitted line carries a timestamp, the level, an event slug (the log message), the active run -> slide -> request correlation context, any structured fields passed via log_event, and an optional error_code. PII is redacted by bioptimus.observability.anonymize.AnonymizingFilter when enabled.

STRUCTURED_KEY

Custom LogRecord attribute holding the structured-field payload.

JsonFormatter

class JsonFormatter(logging.Formatter)

Formats log records as single-line JSON objects. The output object always includes timestamp (ISO 8601, UTC), level, event (the formatted message), and logger. Structured fields attached via log_event, together with the active correlation context, are merged in at the top level. Exception and stack information, when present, are rendered under exception and stack.

format

def format(record: logging.LogRecord) -> str

Renders the record as a JSON string.

The log record to serialize.

Returns: A single-line JSON document describing the record.

ConsoleFormatter

class ConsoleFormatter(logging.Formatter)

Human-readable single-line formatter for console output. Renders timestamp level event [key=value ...] so logs are easy to scan in a terminal or notebook, while the file handler retains full JSON.

format

def format(record: logging.LogRecord) -> str

Renders the record as a readable text line.

The log record to format.

Returns: A human-readable single-line message, or a compact multiline message when structured fields are present.

log_event

def log_event(logger: logging.Logger,
              level: int,
              event: str,
              *,
              error_code: ErrorCode | str | None = None,
              exc_info: bool | BaseException = False,
              fields: dict[str, Any] | None = None,
              **extra: Any) -> None

Emits a structured log event.

The logger to emit on.

The logging level, for example logging.WARNING.

A short, stable event slug used as the log message, for example "wsi_backend_unavailable".

Optional machine-readable error code recorded under error_code.

Exception information forwarded to the logging call, enabling an exception field in the output.

Structured fields supplied as a single dict, merged into the log object. Callers with untrusted keys (for example an error’s context) pass them here so a key such as error_code cannot collide with this function’s named parameters. Explicit extra keyword arguments win on collision.

Structured fields supplied as keyword arguments, for example backend="cucim" or reason="missing library". Convenient for hardcoded literals at the call site.

log_error

def log_error(logger: logging.Logger,
              error: BioptimusError,
              *,
              level: int = logging.ERROR,
              exc_info: bool | BaseException = False,
              **fields: Any) -> None

Logs a BioptimusError once, with its code, context, and fix. Flattens the error’s structured context and attaches its machine-readable error_code, message, and remediation so a single boundary log line fully explains the failure and how to resolve it. Extra fields override context entries on collision.

The logger to emit on.

The typed error to record.

The logging level. Defaults to logging.ERROR.

Exception information forwarded to the logging call, enabling an exception field in the output.

Extra structured fields merged on top of the error context.

is_logged

def is_logged(exc: BaseException) -> bool

Reports whether a boundary has already logged an exception.

The exception to inspect.

Returns: True when a log_failures boundary has already recorded the exception, so an outer boundary can avoid logging it a second time.

log_failures

def log_failures(func: F | None = None,
                 *,
                 logger: logging.Logger | None = None,
                 level: int = logging.ERROR) -> F | Callable[[F], F]

Logs any failure from a public SDK call once, then re-raises it unchanged. Wraps a public function or method so that any Exception it raises is recorded exactly once before propagating: a BioptimusError is logged with its code, context, and remediation, and any other exception with its type and message, each with a full traceback. The original exception is re-raised unchanged, so existing except handlers and return contracts are preserved. Recording the failure at the boundary the user called guarantees a durable record reaches the configured sink (see configure_logging) even if the process or its console is killed afterwards. Internal helpers do not log; they raise, and the outermost boundary records the failure once. A marker on the exception keeps an outer boundary from logging it again. Both synchronous and asynchronous callables are supported; KeyboardInterrupt, SystemExit, and asyncio.CancelledError do not derive from Exception and are never caught.

The callable to wrap, supplied automatically when used as a bare @log_failures decorator.

Logger to record on. Defaults to the logger named after the wrapped callable’s module.

Level for the boundary log line. Defaults to logging.ERROR.

Returns: The wrapped callable when func is given, otherwise a decorator that wraps a callable.

default_log_file

def default_log_file() -> Path

Returns the default log-file path under the system temp directory. This cross-platform location is bioptimus.log inside the directory reported by tempfile.gettempdir (honoring TMPDIR/TEMP/TMP on the respective platforms). It is where configure_logging falls back to when neither an explicit log_file argument nor the BIOPTIMUS_LOG_FILE environment variable is set, so logging works with no setup while remaining easy to discover and override. Returns: The default log-file path.

get_log_file

def get_log_file() -> Path | None

Returns the log-file path the SDK is currently writing to. Resolution order:

Path set via configure_logging(log_file=...) — highest priority.
BIOPTIMUS_LOG_FILE environment variable (empty string disables).
Default temp path (e.g. /tmp/bioptimus.log).

Returns: The active log-file path, or None when file logging is disabled.

configure_logging

def configure_logging(
    *,
    level: int | str = logging.INFO,
    stream: TextIO | None = None,
    log_file: str | Path | None = None,
    anonymize: bool = False,
    logger_name: str | None = _DEFAULT_LOGGER,
    when: str = _DEFAULT_WHEN,
    backup_count: int = _DEFAULT_BACKUP_COUNT,
    console: bool = False,
    file_handler_factory: Callable[[Path], logging.Handler] | None = None
) -> logging.Logger

Configures structured JSON logging for the SDK. Installs a time-rotating file handler on the target logger, attaching correlation-context injection and optional PII anonymization. Importing the package has no logging side effects; the first emitted event auto-installs this same default configuration, and calling this function explicitly overrides it (for a custom path, level, or anonymization). Repeated calls replace the handlers a previous call installed, so the helper is safe to call more than once. Rotated files are suffixed with the UTC date (for example sdk.log.2026-06-24), which keeps them easy to match to a support window. By default the SDK is silent on the console — log records go only to the file sink (for support bundles) and propagate up Python’s logger hierarchy. If the application has its own root-logger handlers, SDK logs appear there automatically. To additionally install the SDK’s own console handler, pass console=True; passing an explicit stream implies console=True. The file sink works with no setup: when log_file is omitted, the path is resolved from the BIOPTIMUS_LOG_FILE environment variable, and when that is unset it defaults to default_log_file (bioptimus.log under the system temp directory). To send logs elsewhere, pass log_file or set the variable; to disable file logging entirely, set the variable to an empty string. Time-based rotation is the default, but the retention strategy is overridable: pass file_handler_factory to supply any handler (for example a size-based logging.handlers.RotatingFileHandler). The SDK still resolves the path, applies the JSON formatter, injects correlation context, and manages the handler’s lifecycle, so when and backup_count are ignored when a factory is given.

Minimum level to emit, as a level name or numeric level.

Stream for the console handler. When provided, implies console=True. Defaults to sys.stderr when a console handler is installed.

Optional path enabling a time-rotating file handler. When omitted, the BIOPTIMUS_LOG_FILE environment variable is used and, if that is unset, default_log_file; an explicit argument always takes precedence. Setting the variable to an empty string disables file logging.

When True, redacts PII from every emitted record, including the on-disk file (redaction at rest). Defaults to False, so records retain full detail and anonymization happens only on export.

Logger to configure. None targets the root logger; the default targets the "bioptimus" package logger.

Rotation interval passed to logging.handlers.TimedRotatingFileHandler, for example "midnight" (the default), "H", or "D".

Number of rotated files to retain before the oldest is deleted. Defaults to 14, matching the recommended retention window.

When True, installs the SDK’s own console handler with human-readable output on sys.stderr. Defaults to False so the SDK stays silent on the console; log records still propagate to the caller’s logging hierarchy, appearing in whatever handlers the application has configured (e.g. on the root logger).

Optional callable that builds the file handler from the resolved log path, replacing the default logging.handlers.TimedRotatingFileHandler. Enables a different retention strategy (for example size-based rotation via logging.handlers.RotatingFileHandler) while the SDK retains ownership of the path, formatter, and context injection. When given, when and backup_count are ignored.

Returns: The configured logging.Logger.

Overview

Get Started

Preprocessing

Workflows

Troubleshooting

Reference

STRUCTURED_KEY

JsonFormatter

format

ConsoleFormatter

format

log_event

log_error

is_logged

log_failures

default_log_file

get_log_file

configure_logging

​STRUCTURED_KEY

​JsonFormatter

​format

​ConsoleFormatter

​format

​log_event

​log_error

​is_logged

​log_failures

​default_log_file

​get_log_file

​configure_logging

STRUCTURED_KEY

JsonFormatter

format

ConsoleFormatter

format

log_event

log_error

is_logged

log_failures

default_log_file

get_log_file

configure_logging