Support bundles

Before running a full slide, or after something goes wrong, use these tools to check a deployment and package what happened into something you can send to Bioptimus support — nothing here leaves your environment unless you send it yourself. For where logs go and how to customize them, see Logging.

Verify an endpoint — send one synthetic tile and check the response against the model contract.
Inspect your environment — capture a diagnostic snapshot for self-diagnosis before you open a ticket.
Build a support bundle — package diagnostics and logs into a redacted .tar.gz.
Customize what gets redacted — control the redaction policy on anything you export.

Every artifact below is redacted best-effort, not guaranteed PII-free — see What gets shared before sharing one outside your environment.

Verify an endpoint

Before running a full slide, send one synthetic tile through the endpoint and check the response against the model’s contract:

from bioptimus.observability.healthcheck import verify_endpoint

report = verify_endpoint(
    model="h1",                          # model name, e.g. "h1" or "m-optimus"
    backend="local",                     # "remote", "aws", "local", or "huggingface"
    checkpoint="<path-to-checkpoint>.pt2",  # local only
    device="cuda",                       # "cuda" or "cpu" for the in-process backends
)
print(report.summary())  # h1 on local: ok (4 checks)

bioptimus verify --model h1 --backend local --checkpoint <path-to-checkpoint>.pt2
bioptimus verify --model h1 --backend remote --base-url http://localhost:8080
bioptimus verify --model h1 --backend aws --endpoint-name <name> --region-name <region>

The CLI prints a checklist, one line per step:

h1 on local: ok (4 checks)
  [PASS] client_construction (812.4 ms) — Built a local client for h1.
  [PASS] metadata (0.1 ms) — Metadata reports model 'h1'.
  [PASS] embedding_request (156.2 ms) — Endpoint accepted the synthetic tile in embedding mode.
  [PASS] embedding_output_contract (0.0 ms) — Output is 1536 finite value(s), matching the model contract.

Each backend takes its own connection arguments, all passed straight through to Backbone:

Backend	Required arguments	Python	CLI
`remote`	Server base URL	`base_url="http://localhost:8080"`	`--base-url http://localhost:8080`
`aws`	SageMaker endpoint + region	`endpoint_name="<name>"`, `region_name="<region>"`	`--endpoint-name <name> --region-name <region>`
`local`	Checkpoint path + device	`checkpoint="<path>.pt2"`, `device="cuda"`	`--checkpoint <path>.pt2 --device cuda`
`huggingface`	Device (weights auto-downloaded)	`device="cuda"`, `precision="fp16"`	`--device cuda --precision fp16`

For the local backend you can point at the directory holding the checkpoint (model_dir= / --model-dir) instead of naming the .pt2 file. Add --json to print the full HealthReport instead, or --mode embedding/--mode prediction to force a specific mode. The command exits non-zero on any failed check, so it can gate a pipeline before the expensive run starts. Each failure carries its own code and fix — see Error codes:

for check in report.failures:
    print(check.name, check.error_code)  # e.g. client_construction BIO-MODEL-002
    print(check.remediation)              # what to do about it

Read the report

verify_endpoint returns a HealthReport; bioptimus verify --json prints the same object. Every step is a Check, and nothing raises unless you ask it to:

report.ok            # True when every non-skipped check passed
report.summary()     # "h1 on local: ok (4 checks)"
report.checks        # every Check, in execution order
report.failures      # only the checks that ran and failed
report.to_dict()     # JSON-friendly dict (what --json prints, what a bundle stores)

Each Check carries name, passed, skipped, duration_ms, detail, and — on failure — error_code, remediation, and structured context (for example the observed vs. expected output length).

Verify options

Option	Python	CLI	Purpose
Force specific modes	`modes=["embedding"]`	`--mode embedding` (repeatable)	Skip mode auto-detection
Override tile size	`tile_size=(224, 224)`	—	Probe how the endpoint handles another geometry
Seed the synthetic tile	`seed=0`	—	Make two runs byte-identical and comparable
Raise instead of report	`raise_on_failure=True`	(non-zero exit)	Turn the first failure into a `BioptimusRuntimeError`
Bound a slow endpoint	`timeout=30.0`	`--timeout 30`	Cap the wait on the `remote`/`aws` request

By default modes="auto" resolves exactly the modes the model exposes — embedding for the plain backbones, prediction for tissue-seg, both for m-optimus, and embedding-only for the huggingface backend. The tile sent is a deterministic gradient-plus-noise image at the model’s declared tile size, so a synthetic request is never mistaken for customer data in a server log.

Inspect your environment

The same environment snapshot that goes into a bundle is available on its own — useful for self-diagnosis before you open a ticket. It never raises: a probe that cannot run degrades to an {"error": ...} entry instead of failing the snapshot.

from bioptimus.observability.probes import snapshot

snap = snapshot()                    # a plain, JSON-friendly dict
snap["gpu"]["cuda_available"]
snap["dependencies"]["satisfied"]

The snapshot is stamped with schema_version and captured_at and gathers:

Section	Reports
`versions`	Installed versions of the SDK and key dependencies
`dependencies`	Whether installed packages satisfy the SDK’s declared constraints (`satisfied`, `conflicts`)
`host`	Python, platform, interpreter, CPU/RAM, container memory limit, open-file limit
`env`	An allowlist of non-secret, inference-relevant environment variables
`gpu`	Torch/CUDA/driver versions, per-device capability and memory, context health
`wsi_backends`	Which WSI backends (OpenSlide, cuCIM, tifffile) import, and why not
`disk`	Temp-dir free space, writability, and leaked AOTInductor extractions
`pt2_compat`	Whether each `.pt2` checkpoint matches the host GPU/CPU architecture
`models`	Load state, device, and precision of loaded models

Each probe is also callable on its own — for a fast CUDA or checkpoint check without the whole snapshot:

from bioptimus.observability.probes import probe_gpu, probe_pt2_compat

probe_gpu()["cuda_available"]                          # False -> run on a GPU instance
probe_pt2_compat({"h1": "h1.pt2"})[0]["compatible"]   # False -> checkpoint/arch mismatch

A model that loads but fails at inference is almost always a version or architecture mismatch. snap["dependencies"]["conflicts"] and snap["pt2_compat"] pinpoint it in one call — the same evidence support would ask for.

Build a support bundle

One command packages a redacted environment snapshot and logs into a .tar.gz — attach this to a support request:

bioptimus support-bundle --output bundle.tar.gz
# Wrote support bundle to bundle.tar.gz

--categories selects what goes in the bundle: diagnostics (environment snapshot and logs, the default) and/or usage (model-request records only, e.g. for a billing question). Repeat the flag or comma-separate to combine them. Add a per-slide status ledger with --workspace, or fold in a running server’s own diagnostics:

bioptimus support-bundle --categories usage --output usage.tar.gz
bioptimus support-bundle --categories diagnostics,usage --output bundle.tar.gz
bioptimus support-bundle --workspace path/to/workspace --output bundle.tar.gz
bioptimus support-bundle --server-url http://localhost:8080 --output bundle.tar.gz

Or from Python:

from bioptimus.observability.support_bundle import build_support_bundle

archive = build_support_bundle(
    output_path="bundle.tar.gz",
    categories=["diagnostics", "usage"],  # omit to get the default full diagnostics bundle
)
print(archive)  # bundle.tar.gz

What you can put in a bundle:

Contents	Python	CLI
Environment snapshot + logs	default	default
Usage records only	`categories=["usage"]`	`--categories usage`
`.pt2` checkpoint compatibility	`checkpoints={"h1": "h1.pt2"}`	`--checkpoint h1.pt2`
Per-slide status ledger	`workspace="path/"` or `ledger_file="manifest.yaml"`	`--workspace path/` or `--ledger manifest.yaml`
A running server’s own diagnostics	`server_url="http://localhost:8080"`	`--server-url ...`
Endpoint verification (`healthcheck.json`)	`verify={"model": "h1", "backend": "remote", "base_url": "..."}`	—
Loaded-model summary	`models={"h1": model}`	—

The last two are Python-only, since they need a live inference request or in-memory model objects. The bundle finds your log file automatically through BIOPTIMUS_LOG_FILE and includes its rotations; point it at a different file with --log-file / log_file=. Every option writes a single local .tar.gz; nothing is sent anywhere. Both the CLI and Python redact by default. For local self-debugging you can keep full paths and identifiers with --no-anonymize (CLI) or anonymize=False (Python) — never share an unredacted bundle outside your environment.

What’s inside the archive

Extract the .tar.gz and inspect it before sending — every bundle is one directory:

bioptimus-support-<timestamp>/
  manifest.json            # schema version, timestamp, SDK version, anonymized flag, file list
  diagnostics.json         # the redacted environment snapshot (the sections shown above)
  logs/<name>              # each configured log file and its rotations, redacted line by line
  usage.json               # model-request records — only with the usage category
  healthcheck.json         # endpoint verification report — only with verify=
  ledger.yaml              # per-slide status summary — only with --workspace / --ledger
  server_diagnostics.json  # the server's own /diagnostics — only with --server-url
  server_usage.json        # the server's usage records — only with --server-url and usage

manifest.json records whether the bundle was anonymized and the exact file list, so a recipient can confirm what they received. The first three files are always present in a diagnostics bundle; the rest appear only when you request the option that produces them. A running server exposes the same redacted data directly:

/diagnostics is unauthenticated — keep it behind the same VPN or network boundary as the rest of your deployment, never on a public network.

curl "http://localhost:8080/diagnostics?categories=usage" -o usage.json

usage.json

{
  "usage": [
    {
      "event": "model_request_received",
      "model_name": "h1",
      "requested_model_name": "h1",
      "mode": "embedding",
      "endpoint": "/invocations"
    }
  ]
}

On AWS SageMaker, the server itself runs in your own account — its logs land in your CloudWatch, not ours. bioptimus support-bundle still captures the client-side SDK logs and diagnostics; CloudWatch is the source for server-side logs on that platform.

Customize what gets redacted

Redaction is driven by a per-field policy you can inspect and change. Each recognized field takes one of three strategies:

Strategy	Effect	Default for
`Strategy.HASH`	Replace with a stable pseudonym (`sha256:...`), preserving correlation	Identifiers: `slide_id`, `patient_id`, `wsi_id`, …
`Strategy.REDACT`	Replace with `[REDACTED]`, dropping the value	(opt-in)
`Strategy.KEEP`	Keep verbatim; still scrubs embedded paths and user names	Any unrecognized field

The default policy (DEFAULT_CONFIG) hashes every recognized identifier and path field. To apply a different policy — for example, redact slide_id outright instead of hashing it — build an AnonymizationConfig and run your own data (a log entry, a manifest, any dict) through the redactor before you share it:

from bioptimus.observability.anonymize import (
    AnonymizationConfig, Strategy, anonymize_mapping,
)
from bioptimus.observability import read_recent_logs

policy = AnonymizationConfig(overrides={"slide_id": Strategy.REDACT})

for entry in read_recent_logs(anonymize=False):   # read full detail...
    shareable = anonymize_mapping(entry, policy)    # ...then redact with your policy

The building blocks are reusable on any value: hash_identifier, redact_text (paths, URIs, and slide names in free text), scrub_user_paths (home-directory user names), and anonymize_value / anonymize_mapping (a single keyed value, or a whole nested mapping). See the anonymize reference.

What gets shared

Before you share a bundle, know what’s in it:

Hashed, not encrypted. Identifiers and path-like fields (slide/patient IDs, slide_path, …) are replaced with a stable, unsalted hash so the same slide correlates across log lines — not a cryptographic guarantee. Paths embedded in free text are redacted outright.
Nothing is transmitted automatically. Every command above only writes a local file or answers a request you make yourself; sharing it with Bioptimus is a manual step.
Best-effort redaction. Bioptimus makes no warranty that the output is free of PII and accepts no liability for it — review a bundle yourself before sharing it outside your environment. An unrecognized field or path shape can pass through unredacted; in particular, connection arguments such as a SageMaker endpoint_name or region_name aren’t recognized identifier fields, so they pass through unchanged.

Overview

Get Started

Preprocessing

Workflows

Troubleshooting

Reference

Verify an endpoint

Read the report

Verify options

Inspect your environment

Build a support bundle

What’s inside the archive

Customize what gets redacted

What gets shared

​Verify an endpoint

​Read the report

​Verify options

​Inspect your environment

​Build a support bundle

​What’s inside the archive

​Customize what gets redacted

​What gets shared

Verify an endpoint

Read the report

Verify options

Inspect your environment

Build a support bundle

What’s inside the archive

Customize what gets redacted

What gets shared