Lightpanda: the headless browser designed for AI and automation
telemetry: send tool rows as fixed codes, merged per batch
Adrià Arrufat55f747ad0a93
diff --git a/src/browser/tools.zig b/src/browser/tools.zigindex 1b36d0172..a58d1d444 100644--- a/src/browser/tools.zig+++ b/src/browser/tools.zig@@ -268,6 +268,41 @@ pub const Tool = enum {getCookies,getEnv,+ /// Telemetry wire id: append, never renumber. 0 is reserved for a name+ /// that matched no tool.+ pub fn telemetryId(self: Tool) u8 {+ return switch (self) {+ .goto => 1,+ .search => 2,+ .markdown => 3,+ .html => 4,+ .screenshot => 5,+ .links => 6,+ .evaluate => 7,+ .extract => 8,+ .tree => 9,+ .nodeDetails => 10,+ .interactiveElements => 11,+ .structuredData => 12,+ .detectForms => 13,+ .click => 14,+ .fill => 15,+ .scroll => 16,+ .waitForSelector => 17,+ .waitForScript => 18,+ .waitForState => 19,+ .hover => 20,+ .press => 21,+ .selectOption => 22,+ .setChecked => 23,+ .findElement => 24,+ .consoleLogs => 25,+ .getUrl => 26,+ .getCookies => 27,+ .getEnv => 28,+ };+ }+/// State-mutating: surfaces in JavaScript recordings. Read-only tools/// (queries, env probes) stay out so a replay doesn't bloat the script/// with noise.@@ -916,11 +951,29 @@ pub fn call(const start = lp.datetime.milliTimestamp(.awake);const maybe_tool = std.meta.stringToEnum(Tool, tool_name);const result = callInner(arena, session, registry, maybe_tool, tool_name, arguments, opts);- const name = if (maybe_tool) |t| @tagName(t) else "?";- session.browser.app.telemetry.recordToolResult(name, opts.source, result, start);+ const id: u8 = if (maybe_tool) |t| t.telemetryId() else 0;+ session.browser.app.telemetry.recordTool(id, opts.source, telemetryOutcome(result), start);return result;}+fn telemetryOutcome(result: ToolError!ToolResult) TelemetryEvent.Tool.Outcome {+ const r = result catch |err| return errorOutcome(err);+ return if (r.is_error) .is_error else .ok;+}++pub fn errorOutcome(err: ToolError) TelemetryEvent.Tool.Outcome {+ return switch (err) {+ error.FrameNotLoaded => .frame_not_loaded,+ error.InvalidParams => .invalid_params,+ error.NodeNotFound => .node_not_found,+ error.NavigationFailed => .navigation_failed,+ error.NavigationTimeout => .navigation_timeout,+ error.Cancelled => .cancelled,+ error.Timeout => .timeout,+ error.InternalError, error.OutOfMemory => .internal,+ };+}+fn callInner(arena: std.mem.Allocator,session: *lp.Session,diff --git a/src/mcp/Server.zig b/src/mcp/Server.zigindex 92c05d7c0..6a00d7e34 100644--- a/src/mcp/Server.zig+++ b/src/mcp/Server.zig@@ -178,7 +178,7 @@ pub fn sendResult(self: *Self, id: std.json.Value, result: anytype) !void {pub fn handleInitialize(self: *Self, req: protocol.Request) !void {const id = req.id orelse return;if (protocol.clientName(req.params)) |name| {- self.app.telemetry.record(.{ .mcp_client = .{ .name = .init(name) } });+ self.app.telemetry.record(.{ .mcp_client = .fromName(name) });}try self.sendResult(id, protocol.InitializeResult{.protocolVersion = @tagName(protocol.Version.negotiate(req.params)),diff --git a/src/mcp/tools.zig b/src/mcp/tools.zigindex f657ae767..228f42a80 100644--- a/src/mcp/tools.zig+++ b/src/mcp/tools.zig@@ -126,11 +126,12 @@ const extra_tools = [_]McpTool{const all_tools = browser_tool_list ++ extra_tools;/// Tools that bypass the browser-tool dispatch and have their own handlers.-const ExtraTool = enum {- save,- session_new,- session_list,- session_close,+/// Values are telemetry wire ids, kept clear of `browser_tools.Tool`'s.+const ExtraTool = enum(u8) {+ save = 200,+ session_new = 201,+ session_list = 202,+ session_close = 203,};pub fn handleList(server: *Server, arena: std.mem.Allocator, req: protocol.Request) !void {@@ -155,12 +156,11 @@ pub fn handleCall(server: *Server, arena: std.mem.Allocator, req: protocol.Reque.session_list => handleSessionList(server, arena),.session_close => handleSessionClose(server, arena, call_params.arguments),};- const outcome: [:0]const u8 = switch (result) {- .ok => "ok",- .fail => "is_error",- .invalid_params => "InvalidParams",- };- server.app.telemetry.recordTool(@tagName(tool), .mcp, outcome, start);+ server.app.telemetry.recordTool(@backingInt(tool), .mcp, switch (result) {+ .ok => .ok,+ .fail => .is_error,+ .invalid_params => .invalid_params,+ }, start);return switch (result) {.ok => |text| sendToolResultText(server, id, text, false),.fail => |text| sendToolResultText(server, id, text, true),diff --git a/src/script/Runtime.zig b/src/script/Runtime.zigindex d9316fe8f..f3411e191 100644--- a/src/script/Runtime.zig+++ b/src/script/Runtime.zig@@ -21,6 +21,7 @@ const lp = @import("lightpanda");const Schema = @import("Schema.zig");const NodeRegistry = @import("../NodeRegistry.zig");+const TelemetryOutcome = @import("../telemetry/telemetry.zig").Event.Tool.Outcome;const v8 = lp.js.v8;const browser_tools = lp.tools;@@ -510,7 +511,7 @@ fn invokeGoto(break :blk browser_tools.startGoto(arena, self.session, self.registry, args, receiver_frame_id);};const started = maybe_started catch |err| {- self.app.telemetry.recordTool("goto", .script, @errorName(err), started_ms);+ self.app.telemetry.recordTool(BrowserTool.goto.telemetryId(), .script, browser_tools.errorOutcome(err), started_ms);return self.rejectResolver(context, resolver, "navigation failed");};@@ -612,23 +613,23 @@ const Outcome = enum { loaded, failed, timed_out };/// Resolve or reject one pending goto's Promise and free its Globals.fn settlePending(self: *Runtime, context: *const v8.Context, pending: *PendingGoto, outcome: Outcome) void {const resolver: *const v8.PromiseResolver = @ptrCast(v8.v8__Global__Get(&pending.resolver, self.env.isolate.handle));- var result: [:0]const u8 = switch (outcome) {- .loaded => "ok",- .failed => "NavigationFailed",- .timed_out => "NavigationTimeout",+ var result: TelemetryOutcome = switch (outcome) {+ .loaded => .ok,+ .failed => .navigation_failed,+ .timed_out => .navigation_timeout,};switch (outcome) {.loaded => done: {const frame = self.session.findFrameByFrameId(pending.frame_id);if (frame == null or frame.?._last_navigate_error != null) {self.rejectResolver(context, resolver, "navigation failed");- result = "NavigationFailed";+ result = .navigation_failed;break :done;}const this: *const v8.Object = @ptrCast(v8.v8__Global__Get(&pending.receiver, self.env.isolate.handle));self.bindFrameId(context, this, pending.frame_id) catch {self.rejectResolver(context, resolver, "internal: page bind failed");- result = "InternalError";+ result = .internal;break :done;};self.resolveResolver(context, resolver, @ptrCast(this));@@ -636,7 +637,7 @@ fn settlePending(self: *Runtime, context: *const v8.Context, pending: *PendingGo.failed => self.rejectResolver(context, resolver, "navigation failed"),.timed_out => self.rejectResolver(context, resolver, "navigation timed out"),}- self.app.telemetry.recordTool("goto", .script, result, pending.started_ms);+ self.app.telemetry.recordTool(BrowserTool.goto.telemetryId(), .script, result, pending.started_ms);pending.reset();}@@ -645,7 +646,7 @@ fn failAllPending(self: *Runtime, context: *const v8.Context, message: []const ufor (self.pending_gotos.items) |*pending| {const resolver: *const v8.PromiseResolver = @ptrCast(v8.v8__Global__Get(&pending.resolver, self.env.isolate.handle));self.rejectResolver(context, resolver, message);- self.app.telemetry.recordTool("goto", .script, "Cancelled", pending.started_ms);+ self.app.telemetry.recordTool(BrowserTool.goto.telemetryId(), .script, .cancelled, pending.started_ms);pending.reset();}self.pending_gotos.clearRetainingCapacity();diff --git a/src/server/cdp/domains/lp.zig b/src/server/cdp/domains/lp.zigindex a7c160dfc..1e01737c1 100644--- a/src/server/cdp/domains/lp.zig+++ b/src/server/cdp/domains/lp.zig@@ -51,27 +51,24 @@ pub fn processMessage(cmd: *CDP.Command) !void {version,}, cmd.input.action) orelse return error.UnknownMethod;- const start = lp.datetime.milliTimestamp(.awake);- const result = switch (action) {- .dump => dump(cmd),- .getMarkdown => getMarkdown(cmd),- .getSemanticTree => getSemanticTree(cmd),- .getInteractiveElements => getInteractiveElements(cmd),- .getNodeDetails => getNodeDetails(cmd),- .getStructuredData => getStructuredData(cmd),- .getContentSignal => getContentSignal(cmd),- .detectForms => detectForms(cmd),- .clickNode => clickNode(cmd),- .fillNode => fillNode(cmd),- .scrollNode => scrollNode(cmd),- .waitForSelector => waitForSelector(cmd),- .handleJavaScriptDialog => handleJavaScriptDialog(cmd),- .configureCDP => configureCDP(cmd),- .configureLoading => configureLoading(cmd),- .version => version(cmd),- };- cmd.cdp.app.telemetry.recordToolResult(@tagName(action), .cdp, result, start);- return result;+ switch (action) {+ .dump => return dump(cmd),+ .getMarkdown => return getMarkdown(cmd),+ .getSemanticTree => return getSemanticTree(cmd),+ .getInteractiveElements => return getInteractiveElements(cmd),+ .getNodeDetails => return getNodeDetails(cmd),+ .getStructuredData => return getStructuredData(cmd),+ .getContentSignal => return getContentSignal(cmd),+ .detectForms => return detectForms(cmd),+ .clickNode => return clickNode(cmd),+ .fillNode => return fillNode(cmd),+ .scrollNode => return scrollNode(cmd),+ .waitForSelector => return waitForSelector(cmd),+ .handleJavaScriptDialog => return handleJavaScriptDialog(cmd),+ .configureCDP => return configureCDP(cmd),+ .configureLoading => return configureLoading(cmd),+ .version => return version(cmd),+ }}fn version(cmd: *CDP.Command) !void {diff --git a/src/telemetry/lightpanda.zig b/src/telemetry/lightpanda.zigindex efc9fa588..a33820264 100644--- a/src/telemetry/lightpanda.zig+++ b/src/telemetry/lightpanda.zig@@ -120,6 +120,10 @@ pub fn send(self: *LightPanda, raw_event: telemetry.Event) !void {};}+ if (raw_event == .tool and mergeTool(self.pending.items, raw_event.tool)) {+ return;+ }+if (self.pending.items.len >= MAX_PENDING) {self.dropped +|= 1;return;@@ -133,6 +137,19 @@ pub fn send(self: *LightPanda, raw_event: telemetry.Event) !void {self.cond.signal(lp.io);}+/// Folds `tool` into a queued row with the same id, source and outcome.+fn mergeTool(pending: []telemetry.Event, tool: telemetry.Event.Tool) bool {+ for (pending) |*event| switch (event.*) {+ .tool => |*t| if (t.id == tool.id and t.source == tool.source and t.outcome == tool.outcome) {+ t.count +|= tool.count;+ t.duration_ms +|= tool.duration_ms;+ return true;+ },+ else => {},+ };+ return false;+}+fn run(self: *LightPanda) void {// The connection is created, owned, and torn down entirely on this thread;// the network thread never sees it (Transport == .none).@@ -314,20 +331,31 @@ const EventRow = struct {},.tool => |t| {try writer.write("T");- try writer.write(t.name);+ try writer.write(t.id);try writer.write(switch (t.source) {.llm => "L",.user => "U",.script => "S",.mcp => "M",- .cdp => "C",});- try writer.write(t.outcome);+ try writer.write(switch (t.outcome) {+ .ok => "O",+ .is_error => "E",+ .frame_not_loaded => "F",+ .invalid_params => "P",+ .node_not_found => "N",+ .navigation_failed => "V",+ .navigation_timeout => "T",+ .cancelled => "C",+ .timeout => "W",+ .internal => "I",+ });+ try writer.write(t.count);try writer.write(t.duration_ms);},.mcp_client => |c| {try writer.write("C");- try writer.write(c.name);+ try writer.write(@backingInt(c));},}try writer.endArray();@@ -380,7 +408,7 @@ test "Telemetry: event row wire format" {.expected = "[\"B\",42]",},.{- .event = .{ .llm = .{ .provider = "anthropic", .model = .init("claude") } },+ .event = .{ .llm = .{ .provider = "anthropic", .model = .wrap("claude") } },.expected = "[\"L\",\"anthropic\",\"claude\"]",},.{@@ -388,16 +416,16 @@ test "Telemetry: event row wire format" {.expected = "[\"L\",\"nollm\",null]",},.{- .event = .{ .tool = .{ .name = "click", .source = .llm, .outcome = "ok", .duration_ms = 12 } },- .expected = "[\"T\",\"click\",\"L\",\"ok\",12]",+ .event = .{ .tool = .{ .id = 14, .source = .llm, .outcome = .ok, .count = 3, .duration_ms = 12 } },+ .expected = "[\"T\",14,\"L\",\"O\",3,12]",},.{- .event = .{ .tool = .{ .name = "goto", .source = .script, .outcome = "NavigationTimeout", .duration_ms = 0 } },- .expected = "[\"T\",\"goto\",\"S\",\"NavigationTimeout\",0]",+ .event = .{ .tool = .{ .id = 1, .source = .script, .outcome = .navigation_timeout, .duration_ms = 0 } },+ .expected = "[\"T\",1,\"S\",\"T\",1,0]",},.{- .event = .{ .mcp_client = .{ .name = .init("a-very-long-mcp-client-name-over-32-bytes") } },- .expected = "[\"C\",\"a-very-long-mcp-client-name-over\"]",+ .event = .{ .mcp_client = .cursor },+ .expected = "[\"C\",3]",},};@@ -409,6 +437,20 @@ test "Telemetry: event row wire format" {}}+test "Telemetry: tool calls merge by id, source and outcome" {+ var pending = [_]telemetry.Event{+ .{ .run = {} },+ .{ .tool = .{ .id = 14, .source = .llm, .outcome = .ok, .duration_ms = 10 } },+ };+ try testing.expect(mergeTool(&pending, .{ .id = 14, .source = .llm, .outcome = .ok, .duration_ms = 5 }));+ try testing.expectEqual(2, pending[1].tool.count);+ try testing.expectEqual(15, pending[1].tool.duration_ms);++ try testing.expect(!mergeTool(&pending, .{ .id = 14, .source = .mcp, .outcome = .ok, .duration_ms = 5 }));+ try testing.expect(!mergeTool(&pending, .{ .id = 14, .source = .llm, .outcome = .is_error, .duration_ms = 5 }));+ try testing.expect(!mergeTool(&pending, .{ .id = 15, .source = .llm, .outcome = .ok, .duration_ms = 5 }));+}+test "Telemetry: header wire format" {var w = std.Io.Writer.Allocating.init(testing.allocator);defer w.deinit();diff --git a/src/telemetry/telemetry.zig b/src/telemetry/telemetry.zigindex a4fe3ffb3..1fa07c8e0 100644--- a/src/telemetry/telemetry.zig+++ b/src/telemetry/telemetry.zig@@ -60,28 +60,19 @@ fn TelemetryT(comptime P: type) type {}/// `start_ms` is a `datetime.milliTimestamp(.awake)` taken before the call.- pub fn recordTool(self: *Self, name: [:0]const u8, source: Event.Tool.Source, outcome: [:0]const u8, start_ms: u64) void {+ pub fn recordTool(self: *Self, id: u8, source: Event.Tool.Source, outcome: Event.Tool.Outcome, start_ms: u64) void {if (self.disabled) {return;}const elapsed = lp.datetime.milliTimestamp(.awake) -| start_ms;self.record(.{ .tool = .{- .name = name,+ .id = id,.source = source,.outcome = outcome,.duration_ms = std.math.lossyCast(u32, elapsed),} });}- /// "ok", "is_error" for a `ToolResult` that failed in-band, or the error name.- pub fn recordToolResult(self: *Self, name: [:0]const u8, source: Event.Tool.Source, result: anytype, start_ms: u64) void {- const outcome: [:0]const u8 = if (result) |r| blk: {- if (@TypeOf(r) == void) break :blk "ok";- break :blk if (r.is_error) "is_error" else "ok";- } else |err| @errorName(err);- self.recordTool(name, source, outcome, start_ms);- }-pub fn llm_init(_: *Self, provider: [:0]const u8, model: ?[]const u8) Event.LLM {return Event.LLM.init(provider, model);}@@ -139,50 +130,108 @@ pub const Event = union(enum) {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: ?InlineString,+ model: ?Model,- pub fn init(provider: [:0]const u8, _model: ?[]const u8) LLM {- return .{- .provider = provider,- .model = if (_model) |m| .init(m) else null,- };- }- };+ const Model = struct {+ len: u8,+ buffer: [32]u8,- pub const Tool = struct {- // Only ever a @tagName or @errorName: static memory that outlives the- // queue, and never a caller-supplied string.- name: [:0]const u8,- source: Source,- outcome: [:0]const u8,- duration_ms: u32,+ pub fn wrap(_s: ?[]const u8) ?Model {+ if (_s == null) return null;- pub const Source = enum { llm, user, script, mcp, cdp };- };-- pub const McpClient = struct {- name: InlineString,- };+ const l = @min(_s.?.len, 32);+ var m: Model = .{+ .len = l,+ .buffer = undefined,+ };+ @memcpy(m.buffer[0..l], _s.?[0..l]);- pub const InlineString = struct {- len: u8,- buffer: [32]u8,+ return m;+ }- pub fn init(s: []const u8) InlineString {- const l = @min(s.len, 32);- var m: InlineString = .{ .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 jsonStringify(self: *const InlineString, 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),+ };}};};@@ -191,6 +240,16 @@ 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"));