Concepts
Logs
Structured execution logs emitted at every level of the workflow hierarchy — accessible per run, per phase, and per step.
Every workflow execution produces structured logs. The platform captures output at each level of the hierarchy — workflow, phase, and step — and makes it available in the run detail view, via the API, and through the SDK.
For
unitelabs-sdk< 0.10.0, import flow and task from Prefect instead. Use flow in place of both workflow and phase decorators, and task as step decorators.Log levels
| Level | Emitted by |
|---|---|
WORKFLOW | Workflow start, end, and top-level workflow engine events |
PHASE | Phase start, end, constraint evaluations, device lock/unlock |
STEP | Step start, end, retry attempts, device commands, logical errors |
ACTION | API requests, responses, and errors |
Writing logs from workflow code
Use Prefect's get_run_logger() anywhere in a workflow, phase, or step:
workflows/sample_prep.py
from prefect.logging import get_run_logger
from unitelabs.sdk.automate import phase
@phase()
async def sample_preparation(plate: Plate, water_source: Plate) -> Plate:
logger = get_run_logger()
logger.info("Starting sample preparation")
await transfer_liquid(source=water_source, target=plate, volume=200)
logger.info("Transfer complete", extra={"volume_ul": 200, "target": plate.identifier})
return plate
Log entries are linked to the phase and step that emitted them, so you can filter the run log to a specific phase without custom tooling.
Accessing logs
Platform UI: open a run and navigate to the Logs tab. Filter by phase, step, or severity level.
API:
Terminal
curl https://api.unitelabs.io/v1/runs/{run_id}/logs \
-H "Authorization: Bearer $API_TOKEN"
Filter to a specific phase:
Terminal
curl "https://api.unitelabs.io/v1/runs/{run_id}/logs?phase=sample_preparation" \
-H "Authorization: Bearer $API_TOKEN"
Automatic log entries
The workflow engine automatically logs these events without any code changes:
- Phase started / completed / failed
- Step started / completed / retried / failed
- Constraint evaluated (condition, outcome)
- Device locked / unlocked
- Transition applied (pre / post)
- Human input requested / received
- API requests and responses
Related concepts
- Runs: logs are scoped to a specific run
- Artifacts: structured data produced by a run, separate from execution logs
- Error Handling: errors appear in logs with full stack traces and retry history