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
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
ConsoleFormatter
timestamp level event [key=value ...] so logs are easy to scan in a terminal or notebook, while the file handler retains full JSON.
format
log_event
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
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.
is_logged
True when a log_failures boundary has already recorded the
exception, so an outer boundary can avoid logging it a second time.
log_failures
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.
Returns:
The wrapped callable when func is given, otherwise a decorator that
wraps a callable.
default_log_file
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
- Path set via
configure_logging(log_file=...)— highest priority. BIOPTIMUS_LOG_FILEenvironment variable (empty string disables).- Default temp path (e.g.
/tmp/bioptimus.log).
None when file logging is disabled.
configure_logging
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.
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.logging.Logger.
