Add BUN_WATCHER_TRACE environment variable for debugging file watcher events

src/Watcher.zig

@@ -95,9 +95,18 @@ pub fn init(comptime T: type, ctx: *T, fs: *bun.fs.FileSystem, allocator: std.me
 
     try Platform.init(&watcher.platform, fs.top_level_dir);
 
+    // Initialize trace file if BUN_WATCHER_TRACE env var is set
+    WatcherTrace.init();
+
     return watcher;
 }
 
+/// Write trace events to the trace file if enabled.
+/// This runs on the watcher thread, so no locking is needed.
+pub fn writeTraceEvents(this: *Watcher, events: []WatchEvent, changed_files: []?[:0]u8) void {
+    WatcherTrace.writeEvents(this, events, changed_files);
+}
+
 pub fn start(this: *Watcher) !void {
     bun.assert(this.watchloop_handle == null);
     this.thread = try std.Thread.spawn(.{}, threadMain, .{this});
@@ -244,6 +253,9 @@ fn threadMain(this: *Watcher) !void {
     }
     this.watchlist.deinit(this.allocator);
 
+    // Close trace file if open
+    WatcherTrace.deinit();
+
     const allocator = this.allocator;
     allocator.destroy(this);
 }
@@ -676,6 +688,7 @@ pub fn onMaybeWatchDirectory(watch: *Watcher, file_path: string, dir_fd: bun.Sto
 
 const string = []const u8;
 
+const WatcherTrace = @import("./watcher/WatcherTrace.zig");
 const WindowsWatcher = @import("./watcher/WindowsWatcher.zig");
 const options = @import("./options.zig");
 const std = @import("std");

src/watcher/INotifyWatcher.zig

@@ -352,6 +352,7 @@ fn processINotifyEventBatch(this: *bun.Watcher, event_count: usize, temp_name_li
     defer this.mutex.unlock();
     if (this.running) {
         // all_events.len == 0 is checked above, so last_event_index + 1 is safe
+        this.writeTraceEvents(all_events[0 .. last_event_index + 1], this.changed_filepaths[0..name_off]);
         this.onFileUpdate(this.ctx, all_events[0 .. last_event_index + 1], this.changed_filepaths[0..name_off], this.watchlist);
     }
 

src/watcher/KEventWatcher.zig

@@ -93,6 +93,7 @@ pub fn watchLoopCycle(this: *Watcher) bun.sys.Maybe(void) {
     this.mutex.lock();
     defer this.mutex.unlock();
     if (this.running) {
+        this.writeTraceEvents(watchevents, this.changed_filepaths[0..watchevents.len]);
         this.onFileUpdate(this.ctx, watchevents, this.changed_filepaths[0..watchevents.len], this.watchlist);
     }
 

src/watcher/WatcherTrace.zig

@@ -0,0 +1,125 @@
+const std = @import("std");
+const bun = @import("../bun.zig");
+const Watcher = @import("../Watcher.zig");
+
+/// Optional trace file for debugging watcher events
+var trace_file: ?bun.sys.File = null;
+
+/// Initialize trace file if BUN_WATCHER_TRACE env var is set.
+/// Only checks once on first call.
+pub fn init() void {
+    if (trace_file != null) return;
+
+    if (bun.getenvZ("BUN_WATCHER_TRACE")) |trace_path| {
+        if (trace_path.len > 0) {
+            const flags = bun.O.WRONLY | bun.O.CREAT | bun.O.APPEND;
+            const mode = 0o644;
+            switch (bun.sys.openA(trace_path, flags, mode)) {
+                .result => |fd| {
+                    trace_file = bun.sys.File{ .handle = fd };
+                },
+                .err => {
+                    // Silently ignore errors opening trace file
+                },
+            }
+        }
+    }
+}
+
+/// Write trace events to the trace file if enabled.
+/// This is called from the watcher thread, so no locking is needed.
+/// Events are assumed to be already deduped by path.
+pub fn writeEvents(watcher: *Watcher, events: []Watcher.WatchEvent, changed_files: []?[:0]u8) void {
+    const file = trace_file orelse return;
+
+    var buffered = std.io.bufferedWriter(file.writer());
+    defer buffered.flush() catch {};
+    const writer = buffered.writer();
+
+    // Get current timestamp
+    const timestamp = std.time.milliTimestamp();
+
+    // Write: { "timestamp": number, "files": { ... } }
+    writer.writeAll("{\"timestamp\":") catch return;
+    writer.print("{d}", .{timestamp}) catch return;
+    writer.writeAll(",\"files\":{") catch return;
+
+    const watchlist_slice = watcher.watchlist.slice();
+    const file_paths = watchlist_slice.items(.file_path);
+
+    var first_file = true;
+    for (events) |event| {
+        const file_path = if (event.index < file_paths.len) file_paths[event.index] else "(unknown)";
+        const names = event.names(changed_files);
+
+        if (!first_file) writer.writeAll(",") catch return;
+        first_file = false;
+
+        // Write path as key
+        writer.print("{}", .{bun.fmt.formatJSONStringUTF8(file_path, .{})}) catch return;
+        writer.writeAll(":{\"events\":[") catch return;
+
+        // Write array of event types
+        var first = true;
+        if (event.op.delete) {
+            if (!first) writer.writeAll(",") catch return;
+            writer.writeAll("\"delete\"") catch return;
+            first = false;
+        }
+        if (event.op.write) {
+            if (!first) writer.writeAll(",") catch return;
+            writer.writeAll("\"write\"") catch return;
+            first = false;
+        }
+        if (event.op.rename) {
+            if (!first) writer.writeAll(",") catch return;
+            writer.writeAll("\"rename\"") catch return;
+            first = false;
+        }
+        if (event.op.metadata) {
+            if (!first) writer.writeAll(",") catch return;
+            writer.writeAll("\"metadata\"") catch return;
+            first = false;
+        }
+        if (event.op.move_to) {
+            if (!first) writer.writeAll(",") catch return;
+            writer.writeAll("\"move_to\"") catch return;
+            first = false;
+        }
+        writer.writeAll("]") catch return;
+
+        // Only write "changed" field if there are changed files
+        var has_changed = false;
+        for (names) |name_opt| {
+            if (name_opt != null) {
+                has_changed = true;
+                break;
+            }
+        }
+
+        if (has_changed) {
+            writer.writeAll(",\"changed\":[") catch return;
+            first = true;
+            for (names) |name_opt| {
+                if (name_opt) |name| {
+                    if (!first) writer.writeAll(",") catch return;
+                    first = false;
+                    writer.print("{}", .{bun.fmt.formatJSONStringUTF8(name, .{})}) catch return;
+                }
+            }
+            writer.writeAll("]") catch return;
+        }
+
+        writer.writeAll("}") catch return;
+    }
+
+    writer.writeAll("}}\n") catch return;
+}
+
+/// Close the trace file if open
+pub fn deinit() void {
+    if (trace_file) |file| {
+        file.close();
+        trace_file = null;
+    }
+}

src/watcher/WindowsWatcher.zig

@@ -293,6 +293,7 @@ fn processWatchEventBatch(this: *bun.Watcher, event_count: usize) bun.sys.Maybe(
 
     log("calling onFileUpdate (all_events.len = {d})", .{all_events.len});
 
+    this.writeTraceEvents(all_events, this.changed_filepaths[0 .. last_event_index + 1]);
     this.onFileUpdate(this.ctx, all_events, this.changed_filepaths[0 .. last_event_index + 1], this.watchlist);
 
     return .success;