Issue Review: cloudflare/workers-sdk#8863

Summary

Wrangler tail --search filter does not take immediate effect when running successive tail sessions - unfiltered log messages from previous session appear for ~10 seconds before filters apply.

Findings

• Created: 2025-04-09
• Updated: 2025-04-09
• Version: 4.9.1 → 4.60.0 (current)
• Component: Wrangler tail command
• Labels: bug
• Comments: 0

Key Evidence

1. No related PRs or changelog entries - Searched for issue #8863 references, "tail filter" keywords in merged PRs and changelogs; no fixes found.

2. Code analysis confirms client-side implementation is correct:

   • Filters are properly sent in the POST body during tail creation (createTail.ts:140-145)
   • The translateCLICommandToFilterMessage() correctly transforms CLI --search flag to QueryFilter type
   • This matches the fix from PR #1713 (2022) which moved filter passing from websocket to tail creation

3. Root cause is server-side behavior:

   • User's observation: "I think what might be happening based on the timestamps is that old log messages that were queued up with the old filter are printed out in the new tail session"
   • The ~10 second delay and message timestamps (9:55:37-9:55:40 AM appearing after the filter was applied) support this hypothesis
   • The Cloudflare tail infrastructure likely buffers/queues recent log messages and delivers them to newly connected clients before the new filters fully propagate

4. No duplicates found - Searched for similar issues about tail filter delays, queued messages; none found.

Recommendation

Status: KEEP OPEN

Reasoning: This is a legitimate bug report with clear reproduction steps. The issue is likely server-side (Cloudflare API/tail infrastructure) rather than in wrangler client code. Wrangler correctly sends filters on tail creation, but the server appears to deliver buffered logs from before the tail session was created. This should be triaged to the backend team responsible for the tail infrastructure.

Action:

1. Add label indicating this may be a backend/API issue
2. Route to Workers: Workers Observability team (per command metadata owner)
3. Consider adding client-side filtering as a workaround (filter received messages against --search pattern before printing)

Root Cause Analysis

The bug appears to be in the Cloudflare tail infrastructure (server-side), not in wrangler. Code references:

Wrangler sends filters correctly on tail creation:

• packages/wrangler/src/tail/createTail.ts:140-145 - Filters passed in POST body
• packages/wrangler/src/tail/filters.ts:121-155 - translateCLICommandToFilterMessage() correctly transforms CLI args

The issue is that:

1. Cloudflare's tail infrastructure appears to buffer/queue recent log messages
2. When a new tail session is created, these buffered messages are delivered to the client
3. The new session's filters haven't propagated to the buffer by the time these old messages are sent
4. After ~10 seconds, the filters fully take effect and only matching messages arrive

Proposed Solution

Option A: Server-side fix (preferred)

• The Cloudflare tail API should apply filters to buffered messages before sending them to new connections
• Or: clear/reset the message buffer when a new tail session is created with different filters
• This requires backend changes outside of wrangler

Option B: Client-side workaround (wrangler)

• Apply the --search filter client-side before printing messages
• This is a defense-in-depth approach that makes wrangler's filtering more robust

// In packages/wrangler/src/tail/index.ts, around line 130
// Before:
const printLog: (data: WebSocket.RawData) => void =
  args.format === "pretty" ? prettyPrintLogs : jsonPrintLogs;

// After:
const printLog: (data: WebSocket.RawData) => void = (data) => {
  if (args.search) {
    // Client-side filter as defense-in-depth
    const message = JSON.parse(data.toString()) as TailEventMessage;
    const messageText = JSON.stringify(message);
    if (!messageText.includes(args.search)) {
      return; // Skip messages that don't match search filter
    }
  }
  (args.format === "pretty" ? prettyPrintLogs : jsonPrintLogs)(data);
};

Implementation Difficulty

Option A (Server-side): Unknown - requires backend team assessment

Option B (Client-side workaround): Easy

• Single file change: packages/wrangler/src/tail/index.ts
• ~15 lines of code
• Low risk - only affects message display, not tail session management
• Could be extended to support other filter types (method, status, header, IP)

Files That Would Need Modification

For client-side workaround:

• packages/wrangler/src/tail/index.ts - Add client-side filtering before print
• packages/wrangler/src/tail/filters.ts - Optionally export filter matching functions for client-side use

Testing Recommendations

1. Manual testing:

   • Run wrangler tail without filters, generate logs
   • Quickly switch to wrangler tail --search "specific-text"
   • Verify no non-matching messages appear

2. Automated testing:

   • Add unit tests for client-side filter matching in filters.test.ts
   • Add integration test that verifies search filter behavior

3. Edge cases to test:

   • Multiple rapid tail session switches
   • High-volume workers (where sampling mode kicks in)
   • Combination filters (--search + --status + --method)

Suggested Comment

Thank you for the detailed bug report!

After investigating the wrangler codebase, I can confirm that wrangler correctly sends filters to the API when creating a tail session. The issue appears to be server-side - the Cloudflare tail infrastructure seems to buffer/queue recent log messages, and these get delivered before the new filters fully propagate.

We're routing this to the backend team for investigation. In the meantime, would you like us to add a client-side workaround that applies the --search filter locally before printing messages? This would provide immediate filtering while the root cause is addressed.