Logs and debugging

Debugging starts with three questions. Is the Service failing now, what evidence explains it, and what is the next useful action? Tokay keeps those answers on the Service page so you do not have to reconstruct an incident from separate systems.

Last updated

AI agent? Start with llms.txt.

Status and alerts tell you when to look

The dashboard summarizes each Service with a status. Green means the Service is working. Red means Tokay observed an incident such as a crash or failed run. Gray means the Service was intentionally stopped.

When a Service stays in trouble, Tokay emails you, and a second email says when it's working again. How alerts work, below, has the timing.

How alerts work

Alerts go to each Owner of the Workspace. Other members don't receive them.

What happens An alert starts after
A web app, webhook, or background worker stops, keeps crashing, or fails most of its requests 5 minutes in a row
The Workspace server stops responding 5 minutes in a row
A scheduled job's runs fail 5 minutes, unless a run succeeds first
A release fails and leaves the maintenance page up No wait
The Workspace disk is 90% full or more Two readings, about 10 minutes
  • Tokay sends the email two minutes after the first problem, so problems that start together arrive in one email.
  • After any alert email, the next one waits at least 15 minutes. If a problem clears during that wait, Tokay doesn't send it.
  • Tokay doesn't send reminders while a problem continues.
  • The recovery email arrives about 10 to 15 minutes after the problem clears, and only if you got the alert. A full disk counts as clear once it drops below 85%.
  • Nothing is sent for one failed request, a failed deploy while the previous version keeps serving, failed runs started with Run now, paused Services, or Services that have never gone live. A successful Run now does count as recovery.
  • Emails name the Service or Workspace, say what Tokay saw, and link to it. They never include logs or request data.

Tokay judges whether your code is running and, for web apps and webhooks, how it answers requests. An error your code catches and logs while the process keeps running looks healthy. To get an alert about one, let the process exit, or check for the problem in a scheduled job. See Background workers and Scheduled jobs.

Logs match the way each Service runs

Web apps and background workers stream recent standard output and error while the process runs. Important incident output, such as the tail from a crash, is preserved after the process exits.

Scheduled jobs keep one record per run with its output, duration, and result. Webhooks add a Requests tab with payloads and Copy as cURL for replay.

The Events tab is the timeline for starts, stops, incidents, recoveries, deployments, and configuration changes.

Diagnoses translate platform failures

Tokay attaches a plain explanation and next action to failed analysis, builds, deployments, and runtime incidents. A process stopped by memory pressure reports Ran out of memory rather than only an exit code. A web app that starts but fails health checks shows an unhealthy state with the boot output available.

Clear fixes can become change proposals

When a diagnosis has a clear fix, Tokay may propose a code change. The proposal appears as a diff and is applied only after you review it. See Editing your code.

Read the evidence before changing the code

A failed build points to dependency or compilation output. An unhealthy web app points to startup or health check behavior. A webhook 5xx points to the recorded request and the handler logs. A scheduled job failure points to one run and its complete output.

See Troubleshooting for symptom based checks across deployment, git, jobs, webhooks, access, and files.