Tail Worker Template

A Cloudflare Workers template that monitors other Workers for errors and sends email notifications when critical issues are detected.

Overview

This project implements a Tail Worker that listens to execution events from other Cloudflare Workers. When errors occur, it automatically sends email alerts with detailed information about the failures.

Features

• Monitors Worker execution outcomes (exceptions, CPU exceeded, etc.)
• Sends email notifications for critical errors
• Includes exception details and stack traces
• Aggregates multiple errors into a single alert

Configuration

1. Set up Environment Variables

For Local Development

Copy the .dev.vars.example file to .dev.vars and update with your email addresses:

cp .dev.vars.example .dev.vars

Edit .dev.vars:

# Email sender information
SENDER_NAME=Your Sender Name
SENDER_ADDR=sender@yourdomain.com

# Email recipient information
RECIPIENT_NAME=Your Recipient Name
RECIPIENT_ADDR=recipient@yourdomain.com

Note: .dev.vars is git-ignored and should never be committed to version control.

For Production Deployment

Set environment variables using the Cloudflare Dashboard or Wrangler CLI:

Option A: Using Cloudflare Dashboard

1. Go to Workers & Pages > Your Worker > Settings > Variables
2. Add the following environment variables:
   • SENDER_NAME
   • SENDER_ADDR
   • RECIPIENT_NAME
   • RECIPIENT_ADDR

Option B: Using Wrangler CLI

wrangler secret put SENDER_NAME
wrangler secret put SENDER_ADDR
wrangler secret put RECIPIENT_NAME
wrangler secret put RECIPIENT_ADDR

2. Set up Email Routing

Configure Cloudflare Email Routing for your domain to enable email sending capabilities.

3. Bind with other Workers

To enable this Tail Worker to monitor other Workers, you need to create a tail consumer binding:

Using Wrangler CLI:

wrangler tail <WORKER_NAME> --format json | wrangler tail <THIS_TAIL_WORKER_NAME>

Or configure via wrangler.toml of the Worker you want to monitor:

[[tail_consumers]]
service = "tail-worker"  # Name of this Tail Worker

Or wrangler.jsonc:

{
    "tail_consumers": [
        {
            "service": "tail-worker"
        }
    ]
}

Or use the Cloudflare Dashboard:

1. Go to Workers & Pages
2. Select the Worker you want to monitor
3. Navigate to Settings > Triggers
4. Add a Tail Consumer and select this Tail Worker

For more details, refer to the Tail Workers documentation.

How It Works

The Tail Worker implements the tail() handler that receives execution events from monitored Workers:

1. Event Monitoring: Listens to all execution events from Workers
2. Error Detection: Identifies failures (exceptions, CPU exceeded, etc.)
3. Error Aggregation: Collects all critical errors with detailed information
4. Email Notification: Sends an alert email containing:
   • Number of errors detected
   • Worker script names
   • Outcome types
   • Exception messages and stack traces

Error Types Detected

The worker monitors various error outcomes:

• exception - Runtime exceptions
• exceededCpu - CPU time limit exceeded
• exceededMemory - Memory limit exceeded
• Other non-ok and non-canceled outcomes

Example Email Alert

Subject: CRITICAL ALERT: 1 Worker Error(s) Detected

Worker 実行中に以下のエラーが検出されました:

[WORKER ERROR] Script: producer-worker-name, Outcome: exception
Exception: ReferenceError: undefined_value is not defined
Stack:
    at Object.fetch (index.js:4:17)

Environment Types

The project uses TypeScript with generated types for Cloudflare Workers bindings:

interface Env {
	SENDER_NAME: string;
	SENDER_ADDR: string;
	RECIPIENT_NAME: string;
	RECIPIENT_ADDR: string;
	send_email_bindings: SendEmail;
}

Links

• Cloudflare Tail Workers Documentation
• Cloudflare Email Routing
• Wrangler Configuration