Skip to main content

Log Streaming

Stream real-time logs from your deployed worker for debugging and monitoring using npm run tail.

Starting the Log Stream

bash
npm run tail

This requires CLOUDFLARE_API_TOKEN to be set in the .env file in the project root, which the script uses to manage tail sessions. The stream outputs color-formatted log entries to the terminal and writes raw JSON lines to tail-logs.jsonl for later analysis.

warning

wrangler tail itself runs outside the project and doesn't read that .env file, so it also needs wrangler login (or CLOUDFLARE_API_TOKEN exported in your shell).

Session Management

Log streaming sessions have a limited lifespan set by Cloudflare. The script handles this automatically:

  • Fetches the actual session expiry time from the Cloudflare API.
  • Restarts the session with a 5-minute buffer before expiry.
  • Cleans up stale sessions on startup.
  • Shuts down gracefully on Ctrl+C.

Output Format

Log entries are color-coded by event type and status:

  • HTTP events — Method, status code, URL, HTTP version, country, network provider and ASN, user agent, and per-server delivery results. The delivery results appear only when show_response_output is on, because they come from the logged response.
  • Email events — From/to/subject, the tail outcome, and interpreter results.

Durable Delivery Events

The delivery outbox writes two structured JSON events independently of show_response_output:

debug valueMeaning
delivery_outbox_retryA transient failure remains at the head of its context lane, and one backoff alarm is armed for another attempt.
delivery_outbox_discardedA permanent failure, or a transient failure past both the 24-hour age limit and three-attempt minimum, was removed so later notifications can continue.

Both events include deliveryId, classification, reason, httpStatus, attemptCount, and ageMilliseconds. httpStatus contains the ntfy response code, including the actual 4xx or 5xx status, instead of a generic delivery-mode message. It is null when a thrown error—such as invalid queued JSON or a missing configured server—has no HTTP response.

When a discarded notification's context has an error_topic, the proxy also sends a one-shot error-debug.json attachment with the delivery ID, reason, HTTP status, attempt count, and age. That diagnostic bypasses the outbox, so its failure does not create another retry event or block the lane.

Config Resolution

The script discovers config.json from the current directory, project root, or XDG config directory, and asks which Worker to tail when it finds more than one. It uses the worker_name from your config to identify the correct Worker on Cloudflare, and the base_domain to find your account.