Skip to content

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.zig
index 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.zig
index 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.zig
index 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.zig
index 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 u
for (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.zig
index 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.zig
index 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.zig
index 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"));