Docs menu

Operate

Monitoring and logs

See what your services are doing, get alerts where you work, and find out why something broke.

Explain it

CLI keeps your apps' logs, counts their requests and errors, and records everything that happens in a project, with no setup. You can get alerts where you work and ask questions about an app in plain words.

How to use it:

  • Logs: open an app's Logs tab; search, pause, or switch to plain English.
  • Alerts: in project settings, connect Slack, Discord, Telegram or a webhook under Alerts (see /docs/alerts-and-webhooks), or install the dashboard on your phone for notifications.
  • Ask: "Why is my app slow today?" from the dashboard's Ask CLI button.

There's also a weekly summary by email, and the home page shows what changed since you last looked.

CLI records what happens in every project as a stream of events, keeps your apps' output, and collects request metrics, traces and grouped errors without extra setup. This page covers how to read all of it, how to get alerts in Slack, Discord, Telegram or your own webhook, and how to ask questions about a service in plain words.

Events

Every project has one event stream: deploys starting, succeeding and failing, services going down and coming back, money running low, approvals, and more. Agents can react to it instead of polling many endpoints, and the dashboard uses it to refresh live. Events are kept for 7 days.

Read recent events

From your terminal:

Terminal
cli events
cli events --kinds deploy_failed,service_down

Ask your agent:

"What happened in the shop project since this morning?"

Agents use the cli_events tool. Passing after (the next value from the last call) returns only new events, and waitSeconds waits for the next one instead of polling.

With the API:

API
GET /v1/projects/:id/events?after=<seq>&kinds=deploy_failed,service_down

The answer holds events and next. Pass next as after on your next call to pick up where you left off.

Follow events live

From your terminal:

Terminal
cli events -f

With the API:

API
GET /v1/projects/:id/events/stream

This is a server-sent event stream. Each message carries the event's sequence number as its id, so a client that reconnects with Last-Event-ID (or ?after=<seq>) gets what it missed. A stream stays open for up to an hour; reconnect after that.

Event kinds

AreaEvents
Deploysdeploy_queued, deploy_succeeded, deploy_failed, template_deployed, fix_pr_opened
Healthservice_down, service_up, cron_failed, error_new, database_failover
Moneyinsufficient_funds, low_balance, budget_warning, budget_reached, payment_received, outbound_payment, payout, call_refunded
People and agentsapproval_requested, approval_resolved, proposal_created, change_proposed, change_ready, agent_report
Secretssecrets_synced, secrets_rotated
Capacitygpu_available
Accountproject_on_hold, abuse_flag, access_review_due

access_review_due fires when a scheduled access review opens (see /docs/access-reviews). call_refunded fires when a paid call covered by the refund guarantee is refunded (see /docs/refunds). gpu_available tells a service on the GPU waitlist that cards are being held for it (see /docs/scaling).

Notification channels

Channels send events to the places your team already looks. A project can have up to 10 channels, and adding one takes an admin.

ChannelWhat you give it
SlackAn incoming webhook URL (https://hooks.slack.com/…)
DiscordA webhook URL (https://discord.com/api/webhooks/…)
TelegramA bot token from @BotFather and a chat id (numeric, or @channel)
WebhookAny https:// URL; CLI POSTs JSON with kind, projectId, text, data, seq and at

Unless you pick, a new channel gets the events worth interrupting someone for: deploy_failed, insufficient_funds, service_down, service_up, low_balance, cron_failed, project_on_hold, approval_requested, proposal_created, budget_warning, budget_reached and database_failover. CLI sends a test message as soon as you add a channel, so you know it works before something breaks.

From your terminal:

Terminal
cli notify add slack https://hooks.slack.com/services/…
cli notify add telegram <bot-token> <chat-id>
cli notify            # list channels
cli notify test <id>  # send another test message
cli notify rm <id>

Ask your agent:

"Send failed deploys and outages for this project to our Discord webhook."

With the API:

API
POST /v1/projects/:id/channels
{"kind": "slack", "url": "https://hooks.slack.com/services/…", "events": ["deploy_failed", "service_down"]}

GET /v1/projects/:id/channels lists them along with every event kind, POST /v1/projects/:id/channels/:channel/test sends a test, and DELETE /v1/projects/:id/channels/:channel removes one.

Webhook, Slack and Discord addresses go through CLI's outbound guard, which refuses private, loopback and cloud-metadata addresses.

Email

Owners and admins are emailed about outages, low balance and approval requests without any setup. To be warned before credit runs out, set a low-balance alert (see /docs/billing).

The inbox

The bell in the dashboard collects what needs a person across all your projects: approvals waiting, failed deploys, outages, proposals from the on-call agent, low credit and on-hold notices. Each item links straight to the right page. You can also turn on browser notifications so the same items arrive as push notifications. New accounts are offered this during setup.

The app on your phone

The dashboard installs as an app. Press Install the app at the bottom of the sidebar or on your account page (in Safari on an iPhone, tap Share, then Add to Home Screen). It opens from your home screen, works with notifications, and shows pages you've already opened when you're offline; changes need a connection. On a phone, a bar along the bottom replaces the sidebar.

The weekly summary

Every Monday afternoon (UTC), people who sign in by email get one email for the week: what each project they own or run cost, how much credit is left and roughly how long it lasts, how many deploys ran and failed, how many changes agents made, and anything waiting for their approval. Turn it off, or see this week's summary, under Account → Weekly summary.

With the API:

API
GET /v1/me/digest
PUT /v1/me/digest
{"weekly": false}

With the API:

API
GET /v1/me/inbox?limit=30
POST /v1/me/inbox/read
{"upTo": <seq>}

Logs

App output is masked: secret values are replaced before you, an agent or a log drain sees them.

From your terminal:

Terminal
cli logs                       # recent output
cli logs -n 500                # more lines
cli logs --grep timeout        # search the last 5000 lines
cli logs --grep "/5\d\d/" --level error
cli logs --deploy <deployId>   # a deploy's build logs

Ask your agent:

"Show me the errors from the api in the last hour."

Agents use cli_service_logs for a running service and cli_logs for one deploy's build and runtime output.

With the API:

API
GET /v1/services/:id/logs?tail=200&q=<text or /regex/>&level=error
GET /v1/deploys/:id/logs

Live output

From your terminal:

Terminal
cli logs -f

With the API:

API
GET /v1/services/:id/logs/stream

A server-sent event stream with one data: event per line. Send your token in the Authorization header.

To keep logs elsewhere, set up a log drain to Datadog, Axiom, Better Stack or any HTTPS endpoint (see /docs/storage-and-secrets).

Request metrics

CLI counts requests per hour, 4xx and 5xx responses, and p50 and p95 latency for each app. Check it after a deploy to see whether errors went up.

Ask your agent:

"Did the error rate on web go up after the last deploy?"

Agents use cli_request_metrics.

With the API:

API
GET /v1/services/:id/requests?hours=24

Traces and slow routes

Apps are deployed with OTEL_EXPORTER_OTLP_* already set, so any OpenTelemetry SDK sends spans to CLI with no setup. Traces are kept for three days.

From your terminal:

Terminal
cli traces           # recent requests with timings
cli traces --slow    # slowest requests and per-route latency
cli traces --failed  # only failed requests

With the API:

API
GET /v1/services/:id/traces?sort=slow
GET /v1/projects/:id/traces/:traceId

The first returns recent or slowest traces plus p50 and p95 per route; the second returns every span of one trace with timings.

Error groups

Exceptions reported through OpenTelemetry are grouped by type, normalized message and top frame, with a count and example traces. A new group raises an error_new event. If you mark a group resolved and it happens again, it reopens and raises error_new again.

From your terminal:

Terminal
cli errors              # open groups
cli errors --all        # including resolved and ignored
cli errors <id>         # one group in detail
cli errors resolve <id>
cli errors ignore <id>
cli errors reopen <id>

With the API:

API
GET /v1/projects/:id/errors?status=open
PATCH /v1/errors/:id
{"status": "resolved"}

Ask about your service

ask reads a service's recent output, deploys, error groups and slow routes and answers your question. Its evidence contains only real log lines, and it suggests next steps. It's a quicker start than reading thousands of lines yourself. Without a model configured on the server, it falls back to a keyword search.

From your terminal:

Terminal
cli ask "why is checkout failing?"

Ask your agent:

"Why is the api returning 500s?"

With the API:

API
POST /v1/services/:id/ask
{"question": "why did checkout start failing?"}

The live canvas and replay

The project page draws your project as a map: each service is a box, lines show which app uses which service, and each box shows live status. Requests move along the lines in proportion to traffic, paid calls arrive as coins, and services that just deployed, went down or failed over pulse.

A scrubber replays the last 24 hours. Drag it back and each card shows that service's state at the time (live, deploying or down), with the moments around it: outages, deploys, failovers and every change with its reason.

With the API:

API
GET /v1/projects/:id/timeline?hours=24

This returns services, deploys, incidents, traffic per hour, paid calls and notable moments, for up to 168 hours.

Home: since you last looked

The home screen opens with a summary across all your projects of what happened since your last visit: approvals waiting, services down, what agents and people changed, deploys, outages that ended, failovers handled, and money earned and spent. Quiet projects stay quiet.

With the API:

API
GET /v1/home
POST /v1/home/seen

Status pages

A status page shows uptime and incidents for the services you choose, at a public address anyone can open without signing in. Setting one up takes an admin.

With the API:

API
PUT /v1/projects/:id/status-page
{"enabled": true, "slug": "shop", "title": "Shop status", "services": ["svc_…", "svc_…"]}

The page is published at /status/<slug>, and GET /v1/status/<slug> returns the same data as JSON. See Incidents and on-call for how outages are detected.

Posting updates

Uptime shows by itself. When something is wrong, or planned, tell people: on the project page, Status page updates, post a title, how bad it is (minor issue, major outage or maintenance) and a first update. It appears at the top of the status page. Add updates as you go (identified, monitoring, resolved). A major outage turns the page's summary red until it's resolved.

API
POST /v1/projects/:id/status-notices {"title": "Checkout is slow", "impact": "major", "status": "investigating", "message": "We're looking into it."}
POST /v1/projects/:id/status-notices/:notice/updates {"status": "resolved", "message": "Fixed: a slow query."}

Alerts on log lines

Get told when something shows up in an app's output: payment failed, out of memory, status=5\d\d. On the app's Logs tab, under Alerts on log lines, give the text to watch for and how many times in five minutes before it alerts. CLI follows the output (with secret values hidden), counts matches, and raises log_alert with the latest matching line through the project's alert channels. After an alert, the rule stays quiet for its cooldown (30 minutes by default), however often the text keeps appearing.

API
POST /v1/services/:id/log-alerts {"name": "Payments failing", "pattern": "payment failed", "threshold": 5, "windowMinutes": 10, "cooldownMinutes": 30}
GET /v1/log-alerts/:id/preview

Plain text matches anywhere in a line, ignoring case. Set "isRegex": true for a regular expression; ones that could hang on long lines are refused. preview counts matches in the app's last 1,000 lines, to check a rule before you rely on it. Agents use cli_log_alerts.

Monitoring CLI itself

If you run your own CLI server, point an outside uptime monitor at GET /health/deep. It needs no sign-in and answers 200 when the database answers and a replica holds the leader lease, and 503 when either fails. The body also says whether the newest backup of CLI's own database is at most 48 hours old (checks.platformBackup), which doesn't change the status, so alert on it separately. See SOC 2 readiness.