Skip to content
Looms
Documentation
On this page

Operate Looms

Monitor the execution log, wake scheduling, and downstream indexes separately; each can fail independently. Cloudflare manages the actor infrastructure; you still own application behavior and observability.

Find runs and pending work#

Actor hosts return 501 for global GET /runs and GET /runs/summaries. Maintain an application run registry when starting work, or attach a projector that writes a shared index. Store runId, tenant ownership, definition version, and creation time. Use that registry to route a dashboard to each run's current state and authorized event stream.

The projectors page shows memory, SQLite, and Postgres index helpers. Actor-local SQLite is not a global index across Durable Objects. A cross-run database or external registry must be reachable by each relevant host. Monitor indexing errors and support rebuilding from retained history.

Inspect a stuck run#

  1. Read /runs/:id and its recorded events.
  2. Find the last effect failure, unsatisfied wait, or missing child outcome.
  3. Check event type and correlation identifiers against the wait.
  4. Check the provider outcome before repeating an external action.
  5. Use wake only after resolving the underlying cause; it is not an unconditional retry-all API.

A run may report running while it has a pending human review. Inspect thread state and pendingApprovals instead of treating one aggregate status as a complete work queue.

GET /runs/:id/status returns thread, deadline, and effect execution status.GET /runs/:id/effects narrows that view to durable effect attempts. Retry an operator-reviewed effect with POST /runs/:id/effects/:effectId/retry; protect mutation-capable operations with an authorize hook such as bearerAuth.

Cancellation and intervention#

Use the embed cancellation API for the whole run or a child thread. Cancellation can abort cooperative work but cannot retract a payment or message already accepted externally. Record operator decisions. If an external action needs to be reversed, perform and record that reversal separately.

Monitor execution#

Correlate logs by runId, threadId, effectId, and sequence. Track failed effects, oldest pending approvals, retry deadlines, ambiguous external outcomes, wake latency, provider errors, stream reconnects, and projector lag. Export metrics through your host's observability stack. Do not log secrets or use estimated token usage as an invoice.

After restoring storage or changing alarm infrastructure, call POST /operations/deadlines/rescan to rebuild timer, effect retry, and timeout scheduling from the log.

Backups and retention#

Choose a backup strategy for the host's SQLite and snapshot data and practice restoration. Set retention based on recovery, audit, and privacy requirements. Replication to a lake is not automatically a verified backup; confirm completeness and a restore procedure. Trimming old events changes the history available to replay and new projections.

Debugger#

createLooms can serve a debugger that shows each run's thread tree, event log, replay, and projections. The debugger guide covers setup, access control, views for your own modules, and Durable Object hosts.

Local hosts and timers#

createLocalActorHost opens run cells lazily. Keep a list of known runs and call getCell for those needing timer recovery after restart, or use a host with durable alarms. The in-memory timeout scheduler does not wake a stopped process.