Download run diagnostics
Prerequisites
- UniteLabs platform with API v0.45.0 or later, and app v0.33.0 or later
- A run to troubleshoot, in any state
- API credentials if downloading through the API (see Authentication)
From the platform UI
- In the Runs list, open the run.
- In the run header, click Download diagnostics.
The browser saves the archive as diagnostics-<workflow>-run-<index>.zip. The button is available in every run state. For a run still in progress, the archive holds all logs up to the moment of download.
Via REST API
To download the archive through the API, request the diagnostics of the run. BASE_URL and TOKEN are set as in the Workflows REST API guide:
curl -o diagnostics.zip "$BASE_URL/runs/{run_id}/diagnostics" \
-H "Authorization: Bearer $TOKEN"
Run diagnostics archive contents
The downloaded archive contains a manifest including run metadata such as package versions, run id etc. as well as full logs of a run.
| File | Contents |
|---|---|
logs/run.log | Every log of the run, oldest first: Prefect, the workflow code, the SDK, connectors, and device libraries |
manifest.json | Tenant, run (status, timestamps, and the parameters it was started with), phases with their Prefect flow runs, failure details, platform API and app versions, packages, runtime image, and log levels |
If the run failed, run.failure in the manifest lists the failed phases and steps with the message Prefect recorded, and the first ERROR or CRITICAL line of run.log.
manifest.json and your internal logging logic before sharing the archive outside your company.Read run.log
Each line of run.log starts with the timestamp, level, and logger, then the scope that emitted it: [run] for the workflow outside any phase, [Phase: <name>], or [Phase: <name> › <step>], where the step name can start with Step:.
Timestamps are in UTC, in ISO 8601 format with millisecond precision. A message that spans several lines continues on lines indented by a tab.
2026-11-02T08:57:30.725Z INFO prefect.flow_runs [Phase: Instrument Initialization-0] INSTRUMENT INITIALIZATION
2026-11-02T08:57:30.742Z INFO prefect.task_runs [Phase: Instrument Initialization-0 › Step: Create and Connect Liquid Handler-db4] Creating liquid handler (simulation=False)
Entries for the workflow outside any phase use the scope [run]:
2026-11-02T08:57:30.294Z INFO prefect.flow_runs [run] Beginning flow run 'exotic-porcupine' for flow 'Workflow: Connectivity Loop'
2026-11-02T08:57:30.325Z INFO prefect.flow_runs [run] phases: star_motion=True dummy_pipetting=True bioshake=False cycle_gate=True
2026-11-02T08:57:30.441Z INFO prefect.flow_runs [run] UniteLabs packages: {"unitelabs-labware": "0.40.0", "unitelabs-liquid-handling": "0.42.0", "unitelabs-sdk": "0.20.0"}
Commands from the liquid handling and labware libraries come from unitelabs.* loggers. They give the command name and its arguments as JSON:
2026-11-02T08:57:34.472Z INFO unitelabs.hamilton.pipettes [Phase: Instrument Initialization-0 › Initialize Device-48c] ChannelsProtocol get_initialization {"channel": 0}
The entry records the call, not the value the command returns. The result shows up in the messages of the workflow code that follow, and in the state the step finishes in:
2026-11-02T08:57:36.646Z INFO unitelabs.hamilton.core96 [Phase: Instrument Initialization-0 › Clear Stale Core96 Tips-988] CoRe96 (CO-RE 96) has_tips_fw {}
2026-11-02T08:57:36.646Z INFO unitelabs.hamilton.core96 [Phase: Instrument Initialization-0 › Clear Stale Core96 Tips-988] CoRe96Protocol get_tip_presence {}
2026-11-02T08:57:36.699Z INFO prefect.task_runs [Phase: Instrument Initialization-0 › Clear Stale Core96 Tips-988] - Core96 tip flag clear: OK
2026-11-02T08:57:36.701Z INFO prefect.task_runs [Phase: Instrument Initialization-0 › Clear Stale Core96 Tips-988] Finished in state Completed()
Warnings use the same format with the level WARNING:
2026-11-02T08:57:31.718Z WARNING prefect.task_runs [Phase: Instrument Initialization-0 › Disable Cover Control-ddd] Cover control disabled
DEBUG entries are present only when the run was started with SDK_LOG_LEVEL=DEBUG (SDK, connectors, and device libraries) or PREFECT_LOG_LEVEL=DEBUG (Prefect and workflow code). The logLevels in the manifest are the job variables at the time of the download, so they can differ from what the run used if its deployment or work pool changed in the meantime.
versions.unitelabsPackages) are reported by the SDK when a workflow starts, in SDK releases after 0.19.0, as an INFO log entry: a run on SDK 0.19.0 or earlier does not record them.Next steps
- Logs: log levels, loggers, and what the platform records automatically
- Workflows and runs via REST API: read and filter a run's logs through the API
- Help and support: where to send the archive
Last updated