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.

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.