1# Tail Workers API Reference
2 
3## Handler Signature
4 
5```typescript
6export default {
7  async tail(
8    events: TraceItem[],
9    env: Env,
10    ctx: ExecutionContext
11  ): Promise<void> {
12    // Process events
13  }
14} satisfies ExportedHandler<Env>;
15```
16 
17**Parameters:**
18- `events`: Array of `TraceItem` objects (one per producer invocation)
19- `env`: Bindings (KV, D1, R2, env vars, etc.)
20- `ctx`: Context with `waitUntil()` for async work
21 
22**CRITICAL:** Tail handlers don't return values. Use `ctx.waitUntil()` for async operations.
23 
24## TraceItem Type
25 
26```typescript
27interface TraceItem {
28  scriptName: string;           // Producer Worker name
29  eventTimestamp: number;        // Epoch milliseconds
30  outcome: 'ok' | 'exception' | 'exceededCpu' | 'exceededMemory' 
31         | 'canceled' | 'scriptNotFound' | 'responseStreamDisconnected' | 'unknown';
32  
33  event?: {
34    request?: {
35      url: string;               // Redacted by default
36      method: string;
37      headers: Record<string, string>;  // Sensitive headers redacted
38      cf?: IncomingRequestCfProperties;
39      getUnredacted(): TraceRequest;    // Bypass redaction (use carefully)
40    };
41    response?: {
42      status: number;
43    };
44  };
45  
46  logs: Array<{
47    timestamp: number;           // Epoch milliseconds
48    level: 'debug' | 'info' | 'log' | 'warn' | 'error';
49    message: unknown[];          // Args passed to console function
50  }>;
51  
52  exceptions: Array<{
53    timestamp: number;           // Epoch milliseconds
54    name: string;                // Error type (Error, TypeError, etc.)
55    message: string;             // Error description
56  }>;
57  
58  diagnosticsChannelEvents: Array<{
59    channel: string;
60    message: unknown;
61    timestamp: number;           // Epoch milliseconds
62  }>;
63}
64```
65 
66**Note:** Official SDK uses `TraceItem`, not `TailItem`. Use `@cloudflare/workers-types` for accurate types.
67 
68## Timestamp Handling
69 
70All timestamps are **epoch milliseconds**, not seconds:
71 
72```typescript
73// ✅ CORRECT - use directly with Date
74const date = new Date(event.eventTimestamp);
75 
76// ❌ WRONG - don't multiply by 1000
77const date = new Date(event.eventTimestamp * 1000);
78```
79 
80## Automatic Redaction
81 
82By default, sensitive data is redacted from `TraceRequest`:
83 
84### Header Redaction
85 
86Headers containing these substrings (case-insensitive):
87- `auth`, `key`, `secret`, `token`, `jwt`
88- `cookie`, `set-cookie`
89 
90Redacted values show as `"REDACTED"`.
91 
92### URL Redaction
93 
94- **Hex IDs:** 32+ hex digits → `"REDACTED"`
95- **Base-64 IDs:** 21+ chars with 2+ upper, 2+ lower, 2+ digits → `"REDACTED"`
96 
97## Bypassing Redaction
98 
99```typescript
100export default {
101  async tail(events, env, ctx) {
102    for (const event of events) {
103      // ⚠️ Use with extreme caution
104      const unredacted = event.event?.request?.getUnredacted();
105      // unredacted.url and unredacted.headers contain raw values
106    }
107  }
108};
109```
110 
111**Best practices:**
112- Only call `getUnredacted()` when absolutely necessary
113- Never log unredacted sensitive data
114- Implement additional filtering before external transmission
115- Use environment variables for API keys, never hardcode
116 
117## Type-Safe Handler
118 
119```typescript
120interface Env {
121  LOGS_KV: KVNamespace;
122  ANALYTICS: AnalyticsEngineDataset;
123  LOG_ENDPOINT: string;
124  API_TOKEN: string;
125}
126 
127export default {
128  async tail(
129    events: TraceItem[],
130    env: Env,
131    ctx: ExecutionContext
132  ): Promise<void> {
133    const payload = events.map(event => ({
134      script: event.scriptName,
135      timestamp: event.eventTimestamp,
136      outcome: event.outcome,
137      url: event.event?.request?.url,
138      status: event.event?.response?.status,
139    }));
140    
141    ctx.waitUntil(
142      fetch(env.LOG_ENDPOINT, {
143        method: "POST",
144        headers: { "Content-Type": "application/json" },
145        body: JSON.stringify(payload),
146      })
147    );
148  }
149} satisfies ExportedHandler<Env>;
150```
151 
152## Outcome vs HTTP Status
153 
154**IMPORTANT:** `outcome` is script execution status, NOT HTTP status.
155 
156- Worker returns 500 → `outcome='ok'` if script completed successfully
157- Uncaught exception → `outcome='exception'` regardless of HTTP status
158- CPU limit exceeded → `outcome='exceededCpu'`
159 
160```typescript
161// ✅ Check outcome for script execution status
162if (event.outcome === 'exception') {
163  // Script threw uncaught exception
164}
165 
166// ✅ Check HTTP status separately
167if (event.event?.response?.status === 500) {
168  // HTTP 500 returned (script may have handled error)
169}
170```
171 
172## Serialization Considerations
173 
174`log.message` is `unknown[]` and may contain non-serializable objects:
175 
176```typescript
177// ❌ May fail with circular references or BigInt
178JSON.stringify(events);
179 
180// ✅ Safe serialization
181const safePayload = events.map(event => ({
182  ...event,
183  logs: event.logs.map(log => ({
184    ...log,
185    message: log.message.map(m => {
186      try {
187        return JSON.parse(JSON.stringify(m));
188      } catch {
189        return String(m);
190      }
191    })
192  }))
193}));
194```
195 
196**Common serialization issues:**
197- Circular references in logged objects
198- `BigInt` values (not JSON-serializable)
199- Functions or symbols in console.log arguments
200- Large objects exceeding body size limits
201