Guides
App Events
Read the account-visible activity log for releases, runtime errors, logs, jobs, and webhooks.
For agents: After every publish and whenever something fails, run
userland apps events "$APP_ID" --severity error --limit 25. Filter with--typeusing an exact event type such asjob.failed. Write your own log lines withctx.log, and never log secret values.
Read events
userland apps events "$APP_ID" --limit 25
userland apps events "$APP_ID" --severity error
userland apps events "$APP_ID" --type webhook.rejected
userland apps events "$APP_ID" --release "$RELEASE_ID"
The API equivalent is GET /v0/apps/:app_id/events with optional type, severity (debug, info, warn, error), release_id, limit (1-100, default 100), and cursor. Events are newest first. When more events exist, the response includes a cursor; pass it back to read the next page.
Any member of the app’s platform account can read events. App users inside the published app cannot.
Event types
--type matches the full type exactly.
| Area | Types |
|---|---|
| Releases | release.created, release.activated, release.rolled_back, release.retention_failed, resource.provisioned, resource.omitted |
| Runtime | runtime.request_error, runtime.deploy_failed, runtime.log.debug, runtime.log.info, runtime.log.warn, runtime.log.error |
| Jobs | job.enqueued, job.succeeded, job.retry, job.failed, job.blocked, job.enqueue_failed |
| Webhooks | webhook.received, webhook.queued, webhook.delivered, webhook.rejected, webhook.delivery_failed, webhook.quota_exceeded, webhook.handler_missing |
| Secrets | secret.set, secret.deleted (the event names the secret, never its value) |
| Files and apps | files.uploaded, files.deleted, app.unpublished |
release.retention_failed is a warning that old releases could not be cleaned up; the new release is still live. resource.omitted means a resource from an earlier release is no longer in the new release’s manifest.
runtime.request_error means a server request threw or returned a 5xx; the app visitor got a generic runtime_error response. webhook.rejected usually means a missing or wrong signature, a stale timestamp, or a plan that does not include webhooks.
Write log events
Server code writes its own events with ctx.log:
await ctx.log.info("order created", { order_id: order.id });
await ctx.log.error("payment provider failed", { status: response.status });
Each call becomes a runtime.log.<level> event with your message and metadata. Userland redacts metadata keys that look secret (token, secret, password, api_key, authorization), long token-like values, and values read through ctx.secrets. Treat that as a safety net, not permission to log secrets.
Retention
Events are kept for the plan’s event retention window: Free 1 day, Starter 7 days, Business 30 days, Business Plus 90 days.
For traffic totals, top paths, and error rates over time, use App Analytics.