Logging

The SDK logs every failure once, with a machine-readable error code and full context, to a local JSON file — no setup required. This page covers where logs go, what a line looks like, and how to customize them. To package logs into something you can send to Bioptimus support, see Support bundles.

What the logging layer gives you

Logging is a small, dependency-light layer with a handful of distinct jobs. Each has its own section below — start with whichever capability you need.

You want to…	Use	Section
Keep a durable JSON record of every failure, with zero setup	automatic on first log	Zero setup
Send logs to a file, the console, a custom stream, or your app’s handlers	`configure_logging`, `BIOPTIMUS_LOG_FILE`	Log destinations
Know exactly what a log line contains	`JsonFormatter` output	Default log format
Emit your own structured events, or record every failure of your functions	`log_event`, `log_failures`	Emit your own log entries
Tag every line of a run / slide / request with shared correlation IDs	`bind_context`, `new_trace_id`	Group related log lines
Read logs back as plain dicts, without parsing JSON	`read_recent_logs`, `read_usage_records`	Read your logs back
Change level, rotation interval, retention, or destination	`configure_logging`	Customize logging
Emit SDK logs in your own format, to your own sink	your own `logging` handler (records propagate)	Can I change the log format?
Redact PII in the log file itself, not just on export	`configure_logging(anonymize=True)`	Redact sensitive fields at rest
Catch typed, coded errors in your own code	`BioptimusError`, `ErrorCode`	Handle errors in your code

Every helper on this page imports from the package root:

from bioptimus.observability import (
    configure_logging, default_log_file, get_log_file,
    log_event, log_failures,
    bind_context, get_context, new_trace_id,
    read_recent_logs, read_usage_records,
    BioptimusError, ErrorCode,
)

Zero setup

Logs rotate daily and are kept for 14 days by default. Change this with configure_logging(backup_count=...).

The first emitted event auto-installs a daily-rotating JSON log file under the system temp directory — nothing to configure.

from bioptimus.observability import default_log_file, get_log_file

print(default_log_file())  # the zero-setup fallback, e.g. /tmp/bioptimus.log
print(get_log_file())      # the path actually in use now — honors BIOPTIMUS_LOG_FILE and
                           # configure_logging(); None when file logging is disabled

On first use, if logging falls back to the temp directory, the SDK emits a single log_file_in_temp_dir warning — that location can be wiped on reboot or by a temp-file cleaner. Point logging at a durable path (see Customize logging) to silence it and keep a lasting record.

The log file is not anonymized at rest — it keeps full detail so you can debug locally, and it never contains slide images, tile pixels, or omics values, only pipeline metadata (paths, IDs, error codes, tracebacks). Anonymization of that metadata is applied only when you export a support bundle or query /diagnostics (see Support bundles).

Log destinations

Destination	How	Notes
File (default)	Nothing — zero setup	Writes to `default_log_file()`, under the system temp directory
A different file	`BIOPTIMUS_LOG_FILE=/path/to/file.log` or `configure_logging(log_file="/path/to/file.log")`	The env var also applies to the `bioptimus` CLI
Console (stderr)	`configure_logging(console=True)`	Human-readable, one line per event
A custom stream	`configure_logging(stream=my_stream)`	JSON lines; implies `console=True`
Disabled	`BIOPTIMUS_LOG_FILE=` (empty)	No file sink; records still propagate to your own handlers

export BIOPTIMUS_LOG_FILE=/var/log/bioptimus.log   # custom path
export BIOPTIMUS_LOG_FILE=                          # disable file logging

Default log format

Every line is a single JSON object:

{
  "timestamp": "2026-09-08T12:00:00.123456+00:00",
  "level": "ERROR",
  "event": "wsi_open_failed",
  "logger": "bioptimus.io.wsi",
  "error_code": "BIO-WSI-002",
  "remediation": "Verify the slide path points to a valid, non-truncated, readable WSI file.",
  "trace_id": "01J9Z8Q3F9K2M4N6P8Q0R2S4T6",
  "run_id": "01J9Z8Q3F9K2M4N6P8Q0R2S4T7",
  "exception": "Traceback (most recent call last): ..."
}

Field	Always present	Meaning
`timestamp`	Yes	ISO 8601, UTC
`level`	Yes	`INFO`, `WARNING`, `ERROR`, …
`event`	Yes	Stable event slug, e.g. `wsi_open_failed`
`logger`	Yes	Python logger name that emitted the record
`error_code`	On a `BioptimusError`	One of the codes in Error codes below
`remediation`	When the code has one	The fix for that code
`trace_id` / `run_id` / `slide_id` / `stage`	When bound via `bind_context`	Correlation fields propagated down the pipeline
`exception` / `stack`	On a failure	Full traceback

Emit your own log entries

Wrap your own pipeline functions to get the same one-record-per-failure behavior with log_failures, or emit a one-off structured event with log_event — both write to the log file that’s already active, no configure_logging call required (see Zero setup). In every example below, run_slide is your function and inference is a client you built earlier (for example inference = Inference(...) or model = Backbone(...)) — swap in your own call:

from bioptimus.observability import log_failures


# Records any exception once (with its error code and traceback), then re-raises it.
@log_failures
def run_slide(path: str):
    return inference.predict(path)

from bioptimus.observability import log_failures


# log_failures auto-detects async functions — no separate decorator needed.
@log_failures
async def run_slide(path: str):
    return await inference.predict_async(path)

import logging

from bioptimus.observability import log_failures

logger = logging.getLogger(__name__)


# Log on your own logger, and as a WARNING instead of the default ERROR.
@log_failures(logger=logger, level=logging.WARNING)
def run_slide(path: str):
    return inference.predict(path)

import logging

from bioptimus.observability import log_event

logger = logging.getLogger(__name__)

# Emit a single structured line yourself. Extra keyword args become JSON fields.
log_event(
    logger,
    logging.WARNING,
    "slide_skipped",          # the event slug (becomes the "event" field)
    reason="tissue_mask_empty",  # any extra fields you want on the line
    slide_id="s1234",
)

Each path writes one JSON line to the log file. A failure caught by log_failures looks like:

{
  "timestamp": "2026-09-08T12:00:00.123456+00:00",
  "level": "ERROR",
  "event": "wsi_open_failed",
  "logger": "__main__",
  "error_code": "BIO-WSI-002",
  "remediation": "Verify the slide path points to a valid, non-truncated, readable WSI file.",
  "operation": "run_slide",
  "exception": "Traceback (most recent call last): ..."
}

and the manual log_event call above writes:

{
  "timestamp": "2026-09-08T12:00:00.123456+00:00",
  "level": "WARNING",
  "event": "slide_skipped",
  "logger": "__main__",
  "reason": "tissue_mask_empty",
  "slide_id": "s1234"
}

log_event also accepts error_code= — which auto-attaches the matching remediation — and exc_info=exc to record a caught exception’s traceback on the line. Bind correlation fields once and every log line emitted inside the block is tagged with them automatically — so all lines for a run, a slide, or a request share a trace_id/slide_id you can filter on. Fields whose value is None are ignored, and the previous context is restored on exit (even on error):

from bioptimus.observability import bind_context, get_context, new_trace_id

with bind_context(trace_id=new_trace_id(), slide_id="TCGA-AA-1234"):
    run_slide("slide.svs")   # every log line inside carries trace_id + slide_id
    print(get_context())     # {'trace_id': '01J9Z8...', 'slide_id': 'TCGA-AA-1234'}

new_trace_id() returns a 26-character, time-sortable ID. bind_context accepts any field name — trace_id, run_id, slide_id, and stage are the ones the SDK’s own pipeline sets and surface in the format table above, but you can bind your own (for example batch_id) the same way.

Read your logs back in Python

Read the log file without parsing JSON yourself. Both readers anonymize by default — pass anonymize=False for full local detail:

from bioptimus.observability import read_recent_logs, read_usage_records

recent = read_recent_logs(max_entries=50)  # last N entries of the active file, oldest first
usage = read_usage_records()               # every model-request record, across rotations

Each entry is a plain dict with the fields shown in Default log format. read_recent_logs tails the active file only; read_usage_records spans the active file and all its rotations, so it is the full request history rather than a recent tail.

Customize logging

Call configure_logging to override any default — for a custom path, console output, level, or retention:

from pathlib import Path

from bioptimus.observability import configure_logging

configure_logging(console=True, level="DEBUG", log_file=Path("~/.bioptimus/logs/bioptimus.log").expanduser())

With console=True, matching events also print a compact, human-readable line to stderr instead of the JSON payload above — for example the slide_skipped event from the manual log_event call:

12:00:00 WARNING slide_skipped   reason=tissue_mask_empty   slide_id=s1234

Parameter	Purpose	Default
`level`	Minimum severity to emit	`logging.INFO`
`log_file`	Explicit file path, overrides `BIOPTIMUS_LOG_FILE`	The env var, else `default_log_file()`
`console`	Also print human-readable lines to `stderr`	`False`
`stream`	Custom stream for console output (implies `console=True`)	`None`
`anonymize`	Redact PII at rest, in the file itself	`False`
`when`	Rotation interval (`"midnight"`, `"H"`, `"D"`, …)	`"midnight"`
`backup_count`	Number of rotated files kept	`14`
`file_handler_factory`	Swap in a different handler, e.g. size-based rotation	`None`
`logger_name`	Logger to configure (`None` targets the root logger)	`"bioptimus"`

Set the rotation period and retention with when and backup_count. Rotated files are suffixed with their UTC date (bioptimus.log.2026-06-24), so each maps cleanly to a support window:

configure_logging(when="H", backup_count=48)   # rotate hourly, keep two days
configure_logging(backup_count=0)               # keep every rotated file

For a policy those two parameters can’t express — size-based rotation, say — pass your own handler through file_handler_factory. The SDK still owns the path, the JSON format, and correlation-context injection:

from logging.handlers import RotatingFileHandler

configure_logging(
    file_handler_factory=lambda path: RotatingFileHandler(
        path, maxBytes=50_000_000, backupCount=5, encoding="utf-8"
    ),
)

Can I change the log format?

The on-disk format is structured JSON by design — it is the contract the readers, support bundles, and a server’s /diagnostics all parse — so there is no format parameter. For human-readable output, pass console=True (shown above). To emit SDK logs in your own format to your own destination, attach your own handler. SDK records propagate up Python’s logging hierarchy, so a handler on the bioptimus logger (or the root logger) receives every event:

import logging

handler = logging.StreamHandler()
handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
logging.getLogger("bioptimus").addHandler(handler)

Redact sensitive fields at rest

By default the log file keeps full detail so you can debug locally, and PII is redacted only when you export — when you build a support bundle or query a server’s /diagnostics. To redact the on-disk file itself, turn on redaction at rest:

from bioptimus.observability import configure_logging

configure_logging(anonymize=True)  # redact PII in the file, not only on export

With redaction on, every emitted record is scrubbed before it is written:

Identifier and path fields (slide_id, patient_id, wsi_id, slide_path, output_dir, …) are replaced by a stable hash — the same value keeps the same pseudonym, so “which slide failed” still correlates across every line.
Free text — any path, s3:///file:// URI, or slide file name embedded in a message or traceback under a field the policy doesn’t recognize — is redacted outright instead; the user name in a home-directory path is masked.

The recognized fields and the per-field strategy (hash, redact, or keep verbatim) are configurable — see Support bundles → Customize what gets redacted for the full policy and the anonymize reference.

Redaction is stable pseudonymization for support triage, not encryption. Review what a bundle contains before sharing logs outside your environment.

Handle errors in your code

Every failure the SDK raises is a BioptimusError carrying a machine-readable code, structured context, and an actionable remediation. Catch the base class to handle any SDK failure and read those fields directly:

from bioptimus.observability import BioptimusError, ErrorCode

try:
    inference.predict("slide.svs")
except BioptimusError as err:
    print(err.code)          # ErrorCode.WSI_OPEN_FAILED
    print(err.code.value)    # "BIO-WSI-002"  — the stable support code
    print(err.context)       # {"path": "slide.svs", "errno": 2, ...}
    print(err.remediation)   # "Verify the slide path points to a valid, ..."
    record = err.to_dict()   # JSON-friendly dict for your own logging / telemetry

    if err.code is ErrorCode.WSI_UNSUPPORTED_FORMAT:
        ...                  # branch on a specific failure class

Existing except handlers keep working. Each typed error subclasses the built-in it replaces, so code that already catches the standard exception is unaffected:

Typed error	Also caught by	Raised for
`BioptimusValueError`	`except ValueError`	Invalid input — bad path, unsupported format, malformed file
`BioptimusRuntimeError`	`except RuntimeError`	Invalid state — backend unavailable, model/forward failure, disk full
`BioptimusImportError`	`except ImportError`	A feature needs an optional extra that is not installed

BioptimusImportError names the exact extra to install, so a missing optional dependency is self-explanatory:

from bioptimus.observability.errors import BioptimusImportError

try:
    ...
except BioptimusImportError as err:
    print(err.remediation)   # e.g. "Install ... pip install bioptimus-sdk[torch] ..."

Error codes

Every BioptimusError carries a stable, hyphen-delimited code such as BIO-WSI-002, grouped by domain:

Domain	Prefix	Covers
Whole-slide image reading	`BIO-WSI-xxx`	Opening/reading slide files, missing backends
Tissue masking	`BIO-MASK-xxx`	Tissue mask generation and validation
Tile extraction	`BIO-TILE-xxx`	Extracting tiles from a slide
Bulk-RNA / omics input	`BIO-RNA-xxx`	Omics file schema and content
Request dispatch / transport	`BIO-NET-xxx`	Talking to a remote or AWS endpoint
Model execution	`BIO-MODEL-xxx`	Loading or running a model
Output writing	`BIO-WRITE-xxx`	Writing inference outputs
Slide-level aggregation	`BIO-AGG-xxx`	Combining tile-level results
Environment / runtime	`BIO-ENV-xxx`	Disk space, GPU availability, missing dependencies
Configuration	`BIO-CFG-xxx`	Invalid SDK configuration
Unclassified	`BIO-GEN-xxx`	Fallback for anything else

Each code has a fixed remediation string, the same one attached to its error_code field above and surfaced by verify_endpoint’s failure reports. The full list of codes and remediations is in the API reference.

Overview

Get Started

Preprocessing

Workflows

Troubleshooting

Reference

What the logging layer gives you

Zero setup

Log destinations

Default log format

Emit your own log entries

Read your logs back in Python

Customize logging

Can I change the log format?

Redact sensitive fields at rest

Handle errors in your code

Error codes

​What the logging layer gives you

​Zero setup

​Log destinations

​Default log format

​Emit your own log entries

​Group related log lines

​Read your logs back in Python

​Customize logging

​Can I change the log format?

​Redact sensitive fields at rest

​Handle errors in your code

​Error codes

What the logging layer gives you

Zero setup

Log destinations

Default log format

Emit your own log entries

Group related log lines

Read your logs back in Python

Customize logging

Can I change the log format?

Redact sensitive fields at rest

Handle errors in your code

Error codes