Observability
How to see what your workflows are doing. The embedded dashboard and its auth layer, the engine's event stream and interceptors, OpenTelemetry spans, dependency-free metrics, the diagnostics bus, and the Telescope integration.
A durable run is long-lived and spans processes, retries and deploys, so checking the logs is rarely enough. The engine exposes the same lifecycle events through several surfaces. Pick the ones that match how you already operate.
Start here
- Dashboard: the embedded operations console, a React SPA plus a JSON API mounted into your AdonisJS routes. Filter runs, follow a run's timeline live, fix and replay a bad input, deliver signals and updates, and check the worker fleet's health. It is the quickest way to answer "what is this run waiting on?".
- Dashboard auth: the console's optional session layer. Sign operators in at a built-in login page, or create a session from your already-authenticated app.
Wiring into your stack
- OpenTelemetry: one trace per run and one span per step, with distributed tracing across worker processes, so workflows show up in Jaeger, Grafana or Datadog next to your HTTP traces.
- Metrics: dependency-free run and step counters and duration percentiles.
collectMetricsserves a Prometheus scrape, andattachDurableMetricsreturns a JSON snapshot with p50/p95/max. The dashboard also serves both counters and backlog/worker gauges atGET <path>/api/metrics. - Telescope: runs and steps inside Telescope, alongside your app's requests, queries and jobs, plus a Workflows health dashboard with a per-worker table.
Underneath
- Events & interceptors: the two programmatic hooks into a running engine.
engine.subscribegives you the lifecycle event stream, andengine.useadds middleware around a local step.currentStep()reaches the step logger from code a step calls. - Diagnostics bus: every engine lifecycle event republished on the
@adonis-agora/diagnosticsbus asagora:durable:<type>. Several of the surfaces above are built on this feed. Subscribe to it to route durable events somewhere none of them cover.
Each event is counted once per fleet
With a control plane, every instance also hears the other instances' events, so live views work from any pod. Since 0.51 the recording surfaces (metrics, OpenTelemetry, the diagnostics bridge and therefore Telescope) handle only the events their own instance produced. Scrape or record every pod and sum: each event is counted once. See events from other instances.
These surfaces add up rather than replace each other. A production deployment typically runs the dashboard for people and OpenTelemetry or metrics for alerting, all from the same event stream.
Lucid
The Lucid StateStore driver — persist runs and checkpoints to Postgres, MySQL, or SQLite through @adonisjs/lucid. The migration ships with @adonis-agora/durable; select the store with stores.lucid().
Dashboard
The embedded operations console — a React SPA plus a JSON API mounted into your AdonisJS routes. Filter runs, live-tail a run's timeline, fix-and-replay a bad input, deliver signals/updates/task completions, pause and trigger schedules, act on runs in bulk, and read the worker fleet's health — with the whole wire contract published as OpenAPI 3.1.