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,92 @@
+/// Optional trace file for debugging watcher events
+var trace_file: ?bun.FileDescriptor = 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 = 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.
+pub fn writeEvents(watcher: *Watcher, events: []Watcher.WatchEvent, changed_files: []?[:0]u8) void {
+    const fd = trace_file orelse return;
+
+    var buf: [16384]u8 = undefined;
+    var stream = std.io.fixedBufferStream(&buf);
+    const writer = stream.writer();
+
+    // Get current timestamp
+    const timestamp = std.time.milliTimestamp();
+
+    for (events) |event| {
+        stream.reset();
+
+        const watchlist_slice = watcher.watchlist.slice();
+        const file_paths = watchlist_slice.items(.file_path);
+        const file_path = if (event.index < file_paths.len) file_paths[event.index] else "(unknown)";
+
+        // Write JSON manually for each event
+        writer.writeAll("{\"timestamp\":") catch return;
+        writer.print("{d}", .{timestamp}) catch return;
+        writer.writeAll(",\"index\":") catch return;
+        writer.print("{d}", .{event.index}) catch return;
+        writer.writeAll(",\"path\":") catch return;
+        writer.print("{}", .{bun.fmt.formatJSONStringUTF8(file_path, .{})}) catch return;
+
+        // Write individual operation flags
+        writer.writeAll(",\"delete\":") catch return;
+        writer.writeAll(if (event.op.delete) "true" else "false") catch return;
+        writer.writeAll(",\"write\":") catch return;
+        writer.writeAll(if (event.op.write) "true" else "false") catch return;
+        writer.writeAll(",\"rename\":") catch return;
+        writer.writeAll(if (event.op.rename) "true" else "false") catch return;
+        writer.writeAll(",\"metadata\":") catch return;
+        writer.writeAll(if (event.op.metadata) "true" else "false") catch return;
+        writer.writeAll(",\"move_to\":") catch return;
+        writer.writeAll(if (event.op.move_to) "true" else "false") catch return;
+
+        // Add changed file names if any
+        const names = event.names(changed_files);
+        writer.writeAll(",\"changed_files\":[") catch return;
+        var 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("]}\n") catch return;
+
+        const written = stream.getWritten();
+        _ = bun.sys.write(fd, written);
+    }
+}
+
+/// Close the trace file if open
+pub fn deinit() void {
+    if (trace_file) |fd| {
+        fd.close();
+        trace_file = null;
+    }
+}
+
+const Watcher = @import("../Watcher.zig");
+const bun = @import("../bun.zig");
+const std = @import("std");

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;