Lightpanda: the headless browser designed for AI and automation
const std = @import("std");
const lp = @import("lightpanda");
const App = @import("../App.zig");
const uuidv4 = @import("../id.zig").uuidv4;
const log = lp.log;
const IID_FILE = "iid";
const Allocator = std.mem.Allocator;
pub fn isDisabled() bool {
if (lp.IS_DEBUG or lp.IS_TEST) {
return true;
}
return std.c.getenv("LIGHTPANDA_DISABLE_TELEMETRY") != null;
}
pub const Telemetry = TelemetryT(@import("lightpanda.zig"));
fn TelemetryT(comptime P: type) type {
return struct {
provider: *P,
disabled: bool,
const Self = @This();
pub fn init(app: *App) !Self {
const disabled = isDisabled();
if (lp.IS_DEBUG == false and lp.IS_TEST == false) {
log.info(.telemetry, "telemetry status", .{ .disabled = disabled });
}
const iid: ?[36]u8 = if (disabled) null else getOrCreateId(app.app_dir_path);
const provider = try app.allocator.create(P);
errdefer app.allocator.destroy(provider);
try P.init(provider, app, iid);
return .{
.disabled = disabled,
.provider = provider,
};
}
pub fn deinit(self: *Self, allocator: Allocator) void {
self.provider.deinit();
allocator.destroy(self.provider);
}
pub fn record(self: *Self, event: Event) void {
if (self.disabled) {
return;
}
self.provider.send(event) catch |err| {
log.debug(.telemetry, "record error", .{ .err = err, .type = @tagName(std.meta.activeTag(event)) });
};
}
/// `start_ms` is a `datetime.milliTimestamp(.awake)` taken before the call.
pub fn recordTool(self: *Self, id: u8, source: Event.Tool.Source, outcome: Event.Tool.Outcome, start_ms: u64) void {
const elapsed = lp.datetime.milliTimestamp(.awake) -| start_ms;
self.record(.{ .tool = .{
.id = id,
.source = source,
.outcome = outcome,
.duration_ms = std.math.lossyCast(u32, elapsed),
} });
}
pub fn llm_init(_: *Self, provider: [:0]const u8, model: ?[]const u8) Event.LLM {
return Event.LLM.init(provider, model);
}
};
}
fn getOrCreateId(app_dir_path_: ?[]const u8) ?[36]u8 {
const app_dir_path = app_dir_path_ orelse {
var id: [36]u8 = undefined;
uuidv4(&id);
return id;
};
var buf: [37]u8 = undefined;
var dir = std.Io.Dir.openDirAbsolute(lp.io, app_dir_path, .{}) catch |err| {
log.warn(.telemetry, "data directory open error", .{ .path = app_dir_path, .err = err });
return null;
};
defer dir.close(lp.io);
const data = dir.readFile(lp.io, IID_FILE, &buf) catch |err| switch (err) {
error.FileNotFound => &.{},
else => {
log.warn(.telemetry, "ID read error", .{ .path = app_dir_path, .err = err });
return null;
},
};
var id: [36]u8 = undefined;
if (data.len == 36) {
@memcpy(id[0..36], data);
return id;
}
uuidv4(&id);
dir.writeFile(lp.io, .{ .sub_path = IID_FILE, .data = &id }) catch |err| {
log.warn(.telemetry, "ID write error", .{ .path = app_dir_path, .err = err });
return null;
};
return id;
}
pub const Event = union(enum) {
run: void,
navigate: Navigate,
buffer_overflow: BufferOverflow,
llm: LLM,
tool: Tool,
mcp_client: McpClient,
pub const Navigate = struct {
tls: bool,
context: Context,
pub const Context = enum { page, iframe, popup };
};
/// The provider merges calls with the same id, source and outcome within
/// one batch, so a sent row carries a count and a total duration.
pub const Tool = struct {
/// `browser.tools.Tool.telemetryId()`, or an MCP-only tool's pinned value
/// (200+). 0 is a name that matched no tool.
id: u8,
source: Source,
outcome: Outcome,
count: u32 = 1,
duration_ms: u32,
pub const Source = enum { llm, user, script, mcp };
pub const Outcome = enum {
ok,
is_error,
frame_not_loaded,
invalid_params,
node_not_found,
navigation_failed,
navigation_timeout,
cancelled,
timeout,
internal,
};
};
/// The MCP client, from `clientInfo.name`. Values are wire ids: append,
/// never renumber.
pub const McpClient = enum(u8) {
other = 0,
claude_code = 1,
claude = 2,
cursor = 3,
vscode = 4,
codex = 5,
gemini = 6,
windsurf = 7,
cline = 8,
zed = 9,
goose = 10,
// Ordered: "claude-code" before "claude", "cursor" before the
// "vscode" in Cursor's "cursor-vscode".
const patterns = [_]struct { []const u8, McpClient }{
.{ "claude-code", .claude_code },
.{ "claude", .claude },
.{ "cursor", .cursor },
.{ "windsurf", .windsurf },
.{ "visual studio code", .vscode },
.{ "vscode", .vscode },
.{ "codex", .codex },
.{ "gemini", .gemini },
.{ "cline", .cline },
.{ "goose", .goose },
};
pub fn fromName(name: []const u8) McpClient {
// Exact: "zed" is a common substring.
if (std.ascii.eqlIgnoreCase(name, "zed")) return .zed;
for (patterns) |p| {
if (std.ascii.findIgnoreCase(name, p[0]) != null) return p[1];
}
return .other;
}
};
const BufferOverflow = struct {
dropped: u32,
};
const LLM = struct {
provider: [:0]const u8,
model: ?Model,
const Model = struct {
len: u8,
buffer: [32]u8,
pub fn wrap(_s: ?[]const u8) ?Model {
if (_s == null) return null;
const l = @min(_s.?.len, 32);
var m: Model = .{
.len = l,
.buffer = undefined,
};
@memcpy(m.buffer[0..l], _s.?[0..l]);
return m;
}
pub fn jsonStringify(self: *const Model, writer: anytype) !void {
try writer.write(self.buffer[0..self.len]);
}
};
pub fn init(provider: [:0]const u8, _model: ?[]const u8) LLM {
return .{
.provider = provider,
.model = Model.wrap(_model),
};
}
};
};
extern fn setenv(name: [*:0]u8, value: [*:0]u8, override: c_int) c_int;
extern fn unsetenv(name: [*:0]u8) c_int;
const testing = @import("../testing.zig");
test "telemetry: McpClient.fromName" {
try testing.expectEqual(.claude_code, Event.McpClient.fromName("claude-code"));
try testing.expectEqual(.claude, Event.McpClient.fromName("claude-ai"));
try testing.expectEqual(.cursor, Event.McpClient.fromName("cursor-vscode"));
try testing.expectEqual(.vscode, Event.McpClient.fromName("Visual Studio Code - Insiders"));
try testing.expectEqual(.zed, Event.McpClient.fromName("Zed"));
try testing.expectEqual(.other, Event.McpClient.fromName("customized-client"));
try testing.expectEqual(.other, Event.McpClient.fromName(""));
}
test "telemetry: always disabled in debug builds" {
// Must be disabled regardless of environment variable.
_ = unsetenv(@constCast("LIGHTPANDA_DISABLE_TELEMETRY"));
try testing.expectEqual(true, isDisabled());
_ = setenv(@constCast("LIGHTPANDA_DISABLE_TELEMETRY"), @constCast(""), 0);
defer _ = unsetenv(@constCast("LIGHTPANDA_DISABLE_TELEMETRY"));
try testing.expectEqual(true, isDisabled());
const FailingProvider = struct {
fn init(_: *@This(), _: *App, _: ?[36]u8) !void {}
fn deinit(_: *@This()) void {}
pub fn send(_: *@This(), _: Event) !void {
unreachable;
}
};
var telemetry = try TelemetryT(FailingProvider).init(testing.test_app);
defer telemetry.deinit(testing.test_app.allocator);
telemetry.record(.{ .run = {} });
}
test "telemetry: getOrCreateId" {
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
const dir = try tmp.dir.realPathFileAlloc(testing.io, ".", testing.arena_allocator);
const id1 = getOrCreateId(dir).?;
const id2 = getOrCreateId(dir).?;
try testing.expectEqual(&id1, &id2);
try tmp.dir.deleteFile(testing.io, IID_FILE);
const id3 = getOrCreateId(dir).?;
try testing.expectEqual(false, std.mem.eql(u8, &id1, &id3));
const id4 = getOrCreateId(null).?;
try testing.expectEqual(false, std.mem.eql(u8, &id1, &id4));
try testing.expectEqual(false, std.mem.eql(u8, &id3, &id4));
}
test "telemetry: sends event to provider" {
var telemetry = try TelemetryT(MockProvider).init(testing.test_app);
defer telemetry.deinit(testing.test_app.allocator);
telemetry.disabled = false;
const mock = telemetry.provider;
telemetry.record(.{ .buffer_overflow = .{ .dropped = 1 } });
telemetry.record(.{ .buffer_overflow = .{ .dropped = 2 } });
telemetry.record(.{ .buffer_overflow = .{ .dropped = 3 } });
try testing.expectEqual(3, mock.events.items.len);
for (mock.events.items, 0..) |event, i| {
try testing.expectEqual(i + 1, event.buffer_overflow.dropped);
}
}
const MockProvider = struct {
allocator: Allocator,
events: std.ArrayList(Event),
fn init(self: *MockProvider, app: *App, _: ?[36]u8) !void {
self.* = .{
.events = .empty,
.allocator = app.allocator,
};
}
fn deinit(self: *MockProvider) void {
self.events.deinit(self.allocator);
}
pub fn send(self: *MockProvider, event: Event) !void {
try self.events.append(self.allocator, event);
}
};