From 04981cde2bc79250e69bf94dc81b75692a3da1f5 Mon Sep 17 00:00:00 2001 From: Sayan Samanta Date: Tue, 9 Jun 2026 11:31:44 -0700 Subject: [PATCH 01/13] Add browser telemetry guide for the opt-in model Documents the telemetry feature as it shipped: opt-in category selection, the lightweight default set, and how to consume the SSE stream. - browsers/telemetry/overview: the category model and the three enabling shapes (default set, explicit categories, off), with replace-on-update. - browsers/telemetry/categories: the full taxonomy grouped into browser activity vs operational, the default set, the auto-managed monitor category, and cost notes. Event payload schemas are deferred to the API reference rather than duplicated here. - browsers/telemetry/streaming: consuming via SDK, CLI, and raw SSE, with client-side filtering and seq-based resume. - Sync the CLI reference --telemetry flag and stream categories to the opt-in grammar. Co-authored-by: Cursor --- browsers/telemetry/categories.mdx | 49 +++++++++++++ browsers/telemetry/overview.mdx | 112 ++++++++++++++++++++++++++++++ browsers/telemetry/streaming.mdx | 80 +++++++++++++++++++++ docs.json | 8 +++ reference/cli/browsers.mdx | 7 +- 5 files changed, 253 insertions(+), 3 deletions(-) create mode 100644 browsers/telemetry/categories.mdx create mode 100644 browsers/telemetry/overview.mdx create mode 100644 browsers/telemetry/streaming.mdx diff --git a/browsers/telemetry/categories.mdx b/browsers/telemetry/categories.mdx new file mode 100644 index 0000000..10078c3 --- /dev/null +++ b/browsers/telemetry/categories.mdx @@ -0,0 +1,49 @@ +--- +title: "Telemetry Categories" +description: "The categories a browser session can capture, what each contains, and their cost" +--- + +A category groups related telemetry events and is the unit you enable or disable. Selection is opt-in: a session captures a category only when you turn it on (see [Overview](/browsers/telemetry/overview)). This page lists every category, the event types it carries, and what it costs to capture. + +For the full payload schema of any event type, see the [Stream telemetry events](https://kernel.sh/docs/api-reference/browser-telemetry/stream-telemetry-events-via-sse) endpoint in the API reference. + +## Browser activity + +These categories report what's happening in the page. Capturing any of them attaches a Chrome DevTools Protocol (CDP) collector to the session, so enable only the ones you need. None are in the default set. + +| Category | Captures | Event types | +| --- | --- | --- | +| `console` | Console output from the page | `console_log`, `console_error` | +| `network` | Network requests, responses, and failures | `network_request`, `network_response`, `network_loading_failed`, `network_idle` | +| `page` | Navigation and page lifecycle, including performance signals | `page_navigation`, `page_dom_content_loaded`, `page_load`, `page_tab_opened`, `page_layout_shift`, `page_lcp`, `page_layout_settled`, `page_navigation_settled` | +| `interaction` | Input driven into the page | `interaction_click`, `interaction_key`, `interaction_scroll_settled` | + +## Operational + +These categories report on the session itself rather than page content. They're cheap to capture, and the first four make up the [default set](#the-default-set). + +| Category | Captures | Event types | +| --- | --- | --- | +| `control` | Computer-control API calls against the session | `api_call` | +| `connection` | CDP and live view connect/disconnect activity | `cdp_connect`, `cdp_disconnect`, `live_view_connect`, `live_view_disconnect` | +| `system` | VM-level failures | `system_oom_kill`, `service_crashed` | +| `captcha` | Results of automated captcha solves | `captcha_solve_result` | +| `screenshot` | Periodic screenshots of the session | `monitor_screenshot` | + + +`screenshot` is the most expensive category to capture — each event carries an encoded image. Enable it only when you need visual snapshots, and prefer [live view](/browsers/live-view) or [replays](/browsers/replays) for continuous visibility. + + +## The default set + +When you enable telemetry without naming any categories (`telemetry: { enabled: true }`, or `--telemetry=all`), the session captures the default set — a lightweight bundle of operational signals: + +`control`, `connection`, `system`, `captcha` + +These are inexpensive to leave on and give you a baseline view of session health and control activity without the volume of the browser-activity categories. + +## The monitor category + +`monitor` reports the health of the CDP collector itself: `monitor_disconnected`, `monitor_reconnected`, `monitor_reconnect_failed`, and `monitor_init_failed`. + +It isn't directly settable. It flows automatically whenever any browser-activity category (`console`, `network`, `page`, `interaction`) is captured — since those are what attach the collector — and is silent otherwise. You can still [filter the stream](/browsers/telemetry/streaming) by `monitor` to isolate these events. diff --git a/browsers/telemetry/overview.mdx b/browsers/telemetry/overview.mdx new file mode 100644 index 0000000..20278fb --- /dev/null +++ b/browsers/telemetry/overview.mdx @@ -0,0 +1,112 @@ +--- +title: "Telemetry Overview" +description: "Capture a real-time, categorized stream of what happens inside a browser session" +--- + +Telemetry gives you a real-time stream of events from inside a browser session — console output, network activity, page lifecycle, user interactions, captcha solves, and operational signals like crashes or connection changes. Events are delivered over [Server-Sent Events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events), so you can react to them live or pipe them into your own observability stack. + +## The model + +Every telemetry event belongs to a **category** (`console`, `network`, `page`, and so on). Categories are the unit of control: you choose which categories a session captures, and the stream only carries events from those categories. + +Selection is **opt-in**. A session captures a category only if you explicitly turn it on; anything you don't list stays off. See [Categories](/browsers/telemetry/categories) for the full list, what each one captures, and its cost. + +## Enabling telemetry + +You configure telemetry when you [create a browser](/introduction/create) (and can change it later on update). There are exactly three shapes. + +### Enable the default set + +Set `enabled: true` with no per-category settings to capture the default set — a lightweight bundle of operational signals (`control`, `connection`, `system`, `captcha`) that's cheap to leave on: + + +```typescript Typescript/Javascript +import Kernel from '@onkernel/sdk'; + +const kernel = new Kernel(); + +const browser = await kernel.browsers.create({ + telemetry: { enabled: true }, +}); +``` + +```python Python +from kernel import Kernel + +kernel = Kernel() + +browser = kernel.browsers.create( + telemetry={"enabled": True}, +) +``` + +```bash CLI +kernel browsers create --telemetry=all +``` + + +### Capture specific categories + +List exactly the categories you want under `telemetry.browser`. Only those are captured; everything else stays off. Don't set the top-level `enabled` flag in this case — the presence of category settings is what turns telemetry on: + + +```typescript Typescript/Javascript +const browser = await kernel.browsers.create({ + telemetry: { + browser: { + console: { enabled: true }, + network: { enabled: true }, + }, + }, +}); +``` + +```python Python +browser = kernel.browsers.create( + telemetry={ + "browser": { + "console": {"enabled": True}, + "network": {"enabled": True}, + }, + }, +) +``` + +```bash CLI +kernel browsers create --telemetry=console,network +``` + + +This session captures `console` and `network` only — no page, interaction, or operational events. + +### Disable telemetry + +Set `enabled: false` to capture nothing. This can't be combined with category settings: + + +```typescript Typescript/Javascript +const browser = await kernel.browsers.create({ + telemetry: { enabled: false }, +}); +``` + +```python Python +browser = kernel.browsers.create( + telemetry={"enabled": False}, +) +``` + +```bash CLI +kernel browsers create --telemetry=off +``` + + + +Updating a session's telemetry **replaces** its category selection — it isn't merged with the previous one. Send the complete set of categories you want captured. + + +## What's next + +- [Categories](/browsers/telemetry/categories) — every category, what it captures, the default set, and cost characteristics. +- [Stream telemetry](/browsers/telemetry/streaming) — consume the live stream from the SDK, CLI, or raw SSE, with filtering and reconnection. +- For event payload schemas, see the [Stream telemetry events](https://kernel.sh/docs/api-reference/browser-telemetry/stream-telemetry-events-via-sse) endpoint in the API reference. diff --git a/browsers/telemetry/streaming.mdx b/browsers/telemetry/streaming.mdx new file mode 100644 index 0000000..915b902 --- /dev/null +++ b/browsers/telemetry/streaming.mdx @@ -0,0 +1,80 @@ +--- +title: "Stream Telemetry" +description: "Consume a session's live telemetry stream from the SDK, CLI, or raw SSE" +--- + +Once a session has telemetry [enabled](/browsers/telemetry/overview), you can stream its events in real time. The stream stays open until the session terminates, and each event is wrapped in an envelope with a monotonic `seq` number you can use to reconnect without gaps. + +## Via SDK + +Open the stream and iterate over it. Each item is an envelope with a `seq` and the `event` itself, which carries a `type`, a `category`, and a `ts` timestamp: + + +```typescript Typescript/Javascript +import Kernel from '@onkernel/sdk'; + +const kernel = new Kernel(); + +const stream = await kernel.browsers.telemetry.stream(sessionId); + +for await (const { seq, event } of stream) { + console.log(`#${seq} [${event.category}] ${event.type}`); +} +``` + +```python Python +from kernel import Kernel + +kernel = Kernel() + +with kernel.browsers.telemetry.stream(session_id) as stream: + for envelope in stream: + event = envelope.event + print(f"#{envelope.seq} [{event.category}] {event.type}") +``` + + +## Via CLI + +Stream events to your terminal. The command runs until the session ends or you interrupt it: + +```bash +kernel browsers telemetry stream +``` + +Filter the stream client-side by category or event type (repeatable or comma-separated), and use `-o json` to emit newline-delimited JSON envelopes for piping: + +```bash +# Only network and console events +kernel browsers telemetry stream --categories=network,console + +# Only specific event types +kernel browsers telemetry stream --types=network_response,console_error + +# Machine-readable output +kernel browsers telemetry stream -o json +``` + + +CLI `--categories` and `--types` are applied locally to the stream — they don't change what the session captures. To change capture, update the session's [telemetry categories](/browsers/telemetry/categories). + + +## Via raw SSE + +The stream is a standard [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) endpoint, so any SSE-capable client works: + +```bash +curl -N https://api.onkernel.com/v1/browsers//telemetry/stream \ + -H "Authorization: Bearer $KERNEL_API_KEY" \ + -H "Accept: text/event-stream" +``` + +Each `data:` frame carries one JSON envelope, and the frame's `id:` field is the envelope's `seq`. A keepalive comment is sent every 15 seconds when no events arrive. The `event:` field is never set. + +## Resuming after a disconnect + +To pick up where you left off, resume from the last `seq` you processed — the server replays events after that sequence number. SDK clients reconnect automatically. For raw SSE, send the last seq as the `Last-Event-ID` header; with the CLI, pass `--seq`: + +```bash +kernel browsers telemetry stream --seq 1024 +``` diff --git a/docs.json b/docs.json index 4fa66f3..048e147 100644 --- a/docs.json +++ b/docs.json @@ -147,6 +147,14 @@ ] }, "browsers/extensions", + { + "group": "Telemetry", + "pages": [ + "browsers/telemetry/overview", + "browsers/telemetry/categories", + "browsers/telemetry/streaming" + ] + }, { "group": "Reserved Browsers", "pages": [ diff --git a/reference/cli/browsers.mdx b/reference/cli/browsers.mdx index 5d65cdc..359e597 100644 --- a/reference/cli/browsers.mdx +++ b/reference/cli/browsers.mdx @@ -22,6 +22,7 @@ Create a new browser session. | `--headless` | Launch without GUI/VNC access. | | `--kiosk` | Launch in Chrome kiosk mode. | | `--start-url ` | Initial page to open on launch. | +| `--telemetry ` | Configure [telemetry](/browsers/telemetry/overview) (opt-in): `all` for the default set, `off` to disable, or a comma-separated category list like `console,network`. | | `--output json`, `-o json` | Output raw JSON object. | ### `kernel browsers delete ` @@ -57,7 +58,7 @@ Update a running browser session — change or remove its proxy, load a profile, | `--save-changes` | Save changes back to the profile when the session ends. | | `--viewport ` | Set viewport size (e.g. `1920x1080@25`). | | `--force` | Force a viewport resize even during an active live view or recording. | -| `--telemetry ` | Toggle telemetry: `all` to enable, `off` to disable, or per-category like `network=on,page=off`. | +| `--telemetry ` | Configure [telemetry](/browsers/telemetry/overview) (opt-in, replaces the current selection): `all` for the default set, `off` to disable, or a comma-separated category list like `console,network`. | | `--output json`, `-o json` | Output raw API response as JSON. | ### `kernel browsers curl ` @@ -105,11 +106,11 @@ Stream browser logs from the supervisor or a file path. ## Telemetry ### `kernel browsers telemetry stream ` -Stream live telemetry events (network, console, interaction, page, and system) from a browser session. +Stream live [telemetry](/browsers/telemetry/overview) events from a browser session. Filters are applied client-side and don't change what the session captures. | Flag | Description | |------|-------------| -| `--categories ` | Filter by category: `api`, `console`, `interaction`, `network`, `page`, `system`. | +| `--categories ` | Filter by category: `console`, `network`, `page`, `interaction`, `control`, `connection`, `system`, `screenshot`, `captcha`, `monitor`. | | `--types ` | Filter by event type (e.g. `network_response,console_error`). | | `--seq ` | Resume after sequence number N; replays events with `seq > N` (default: `-1`, stream from now). | | `--output json`, `-o json` | Output newline-delimited JSON envelopes. | From 94bdd8694eeed7732e34570aadd23d96a77048d6 Mon Sep 17 00:00:00 2001 From: Sayan Samanta Date: Tue, 9 Jun 2026 13:18:11 -0700 Subject: [PATCH 02/13] Fold in review feedback from the original telemetry draft Maps the still-valid intent and reviewer feedback from the superseded draft (#384) into the rewritten guide: - Use the unversioned api.onkernel.com/browsers base path in the raw SSE example, matching the API reference and the rest of the docs. - Clarify that interaction events are browser-native DOM events, distinct from the computer-control API (control category), and note that input into sensitive fields like passwords is suppressed. - Replace em dashes with hyphens to match repo style. Co-authored-by: Cursor --- browsers/telemetry/categories.mdx | 12 ++++++++---- browsers/telemetry/overview.mdx | 14 +++++++------- browsers/telemetry/streaming.mdx | 6 +++--- 3 files changed, 18 insertions(+), 14 deletions(-) diff --git a/browsers/telemetry/categories.mdx b/browsers/telemetry/categories.mdx index 10078c3..f459f07 100644 --- a/browsers/telemetry/categories.mdx +++ b/browsers/telemetry/categories.mdx @@ -16,7 +16,11 @@ These categories report what's happening in the page. Capturing any of them atta | `console` | Console output from the page | `console_log`, `console_error` | | `network` | Network requests, responses, and failures | `network_request`, `network_response`, `network_loading_failed`, `network_idle` | | `page` | Navigation and page lifecycle, including performance signals | `page_navigation`, `page_dom_content_loaded`, `page_load`, `page_tab_opened`, `page_layout_shift`, `page_lcp`, `page_layout_settled`, `page_navigation_settled` | -| `interaction` | Input driven into the page | `interaction_click`, `interaction_key`, `interaction_scroll_settled` | +| `interaction` | Browser-native input in the page (clicks, keys, scroll) | `interaction_click`, `interaction_key`, `interaction_scroll_settled` | + + +`interaction` events are browser-native DOM events observed in the page, not calls to the [computer-control](/browsers/computer-controls) API (those are reported by the `control` category). Input into sensitive fields such as passwords is suppressed: `interaction_key` isn't emitted for them, and `interaction_click` omits the element text. + ## Operational @@ -31,12 +35,12 @@ These categories report on the session itself rather than page content. They're | `screenshot` | Periodic screenshots of the session | `monitor_screenshot` | -`screenshot` is the most expensive category to capture — each event carries an encoded image. Enable it only when you need visual snapshots, and prefer [live view](/browsers/live-view) or [replays](/browsers/replays) for continuous visibility. +`screenshot` is the most expensive category to capture - each event carries an encoded image. Enable it only when you need visual snapshots, and prefer [live view](/browsers/live-view) or [replays](/browsers/replays) for continuous visibility. ## The default set -When you enable telemetry without naming any categories (`telemetry: { enabled: true }`, or `--telemetry=all`), the session captures the default set — a lightweight bundle of operational signals: +When you enable telemetry without naming any categories (`telemetry: { enabled: true }`, or `--telemetry=all`), the session captures the default set - a lightweight bundle of operational signals: `control`, `connection`, `system`, `captcha` @@ -46,4 +50,4 @@ These are inexpensive to leave on and give you a baseline view of session health `monitor` reports the health of the CDP collector itself: `monitor_disconnected`, `monitor_reconnected`, `monitor_reconnect_failed`, and `monitor_init_failed`. -It isn't directly settable. It flows automatically whenever any browser-activity category (`console`, `network`, `page`, `interaction`) is captured — since those are what attach the collector — and is silent otherwise. You can still [filter the stream](/browsers/telemetry/streaming) by `monitor` to isolate these events. +It isn't directly settable. It flows automatically whenever any browser-activity category (`console`, `network`, `page`, `interaction`) is captured - since those are what attach the collector - and is silent otherwise. You can still [filter the stream](/browsers/telemetry/streaming) by `monitor` to isolate these events. diff --git a/browsers/telemetry/overview.mdx b/browsers/telemetry/overview.mdx index 20278fb..9fed2f3 100644 --- a/browsers/telemetry/overview.mdx +++ b/browsers/telemetry/overview.mdx @@ -3,7 +3,7 @@ title: "Telemetry Overview" description: "Capture a real-time, categorized stream of what happens inside a browser session" --- -Telemetry gives you a real-time stream of events from inside a browser session — console output, network activity, page lifecycle, user interactions, captcha solves, and operational signals like crashes or connection changes. Events are delivered over [Server-Sent Events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events), so you can react to them live or pipe them into your own observability stack. +Telemetry gives you a real-time stream of events from inside a browser session - console output, network activity, page lifecycle, user interactions, captcha solves, and operational signals like crashes or connection changes. Events are delivered over [Server-Sent Events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events), so you can react to them live or pipe them into your own observability stack. ## The model @@ -17,7 +17,7 @@ You configure telemetry when you [create a browser](/introduction/create) (and c ### Enable the default set -Set `enabled: true` with no per-category settings to capture the default set — a lightweight bundle of operational signals (`control`, `connection`, `system`, `captcha`) that's cheap to leave on: +Set `enabled: true` with no per-category settings to capture the default set - a lightweight bundle of operational signals (`control`, `connection`, `system`, `captcha`) that's cheap to leave on: ```typescript Typescript/Javascript @@ -47,7 +47,7 @@ kernel browsers create --telemetry=all ### Capture specific categories -List exactly the categories you want under `telemetry.browser`. Only those are captured; everything else stays off. Don't set the top-level `enabled` flag in this case — the presence of category settings is what turns telemetry on: +List exactly the categories you want under `telemetry.browser`. Only those are captured; everything else stays off. Don't set the top-level `enabled` flag in this case - the presence of category settings is what turns telemetry on: ```typescript Typescript/Javascript @@ -77,7 +77,7 @@ kernel browsers create --telemetry=console,network ``` -This session captures `console` and `network` only — no page, interaction, or operational events. +This session captures `console` and `network` only - no page, interaction, or operational events. ### Disable telemetry @@ -102,11 +102,11 @@ kernel browsers create --telemetry=off -Updating a session's telemetry **replaces** its category selection — it isn't merged with the previous one. Send the complete set of categories you want captured. +Updating a session's telemetry **replaces** its category selection - it isn't merged with the previous one. Send the complete set of categories you want captured. ## What's next -- [Categories](/browsers/telemetry/categories) — every category, what it captures, the default set, and cost characteristics. -- [Stream telemetry](/browsers/telemetry/streaming) — consume the live stream from the SDK, CLI, or raw SSE, with filtering and reconnection. +- [Categories](/browsers/telemetry/categories) - every category, what it captures, the default set, and cost characteristics. +- [Stream telemetry](/browsers/telemetry/streaming) - consume the live stream from the SDK, CLI, or raw SSE, with filtering and reconnection. - For event payload schemas, see the [Stream telemetry events](https://kernel.sh/docs/api-reference/browser-telemetry/stream-telemetry-events-via-sse) endpoint in the API reference. diff --git a/browsers/telemetry/streaming.mdx b/browsers/telemetry/streaming.mdx index 915b902..00469ff 100644 --- a/browsers/telemetry/streaming.mdx +++ b/browsers/telemetry/streaming.mdx @@ -56,7 +56,7 @@ kernel browsers telemetry stream -o json ``` -CLI `--categories` and `--types` are applied locally to the stream — they don't change what the session captures. To change capture, update the session's [telemetry categories](/browsers/telemetry/categories). +CLI `--categories` and `--types` are applied locally to the stream - they don't change what the session captures. To change capture, update the session's [telemetry categories](/browsers/telemetry/categories). ## Via raw SSE @@ -64,7 +64,7 @@ CLI `--categories` and `--types` are applied locally to the stream — they don' The stream is a standard [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) endpoint, so any SSE-capable client works: ```bash -curl -N https://api.onkernel.com/v1/browsers//telemetry/stream \ +curl -N https://api.onkernel.com/browsers//telemetry/stream \ -H "Authorization: Bearer $KERNEL_API_KEY" \ -H "Accept: text/event-stream" ``` @@ -73,7 +73,7 @@ Each `data:` frame carries one JSON envelope, and the frame's `id:` field is the ## Resuming after a disconnect -To pick up where you left off, resume from the last `seq` you processed — the server replays events after that sequence number. SDK clients reconnect automatically. For raw SSE, send the last seq as the `Last-Event-ID` header; with the CLI, pass `--seq`: +To pick up where you left off, resume from the last `seq` you processed - the server replays events after that sequence number. SDK clients reconnect automatically. For raw SSE, send the last seq as the `Last-Event-ID` header; with the CLI, pass `--seq`: ```bash kernel browsers telemetry stream --seq 1024 From 6641cfb177e2ac1fdcb32a68299efce8422220ca Mon Sep 17 00:00:00 2001 From: Sayan Samanta Date: Tue, 9 Jun 2026 13:32:50 -0700 Subject: [PATCH 03/13] Add telemetry to Observe page and a data-sensitivity section - Surface telemetry as a discovery path on the Observe page: a Telemetry section with stream examples and a "picking the right tool" entry, so readers comparing observability options find it. - Add a Data sensitivity section to the categories guide. Calls out which categories can carry secrets or personal data (console, network, page, interaction, screenshot) versus metadata-only ones, notes the built-in sensitive-field suppression, and frames opt-in scoping as the main control. Modeled on the managed auth privacy guidance. Co-authored-by: Cursor --- browsers/telemetry/categories.mdx | 15 ++++++++++ introduction/observe.mdx | 48 ++++++++++++++++++++++++++++++- 2 files changed, 62 insertions(+), 1 deletion(-) diff --git a/browsers/telemetry/categories.mdx b/browsers/telemetry/categories.mdx index f459f07..b306328 100644 --- a/browsers/telemetry/categories.mdx +++ b/browsers/telemetry/categories.mdx @@ -38,6 +38,21 @@ These categories report on the session itself rather than page content. They're `screenshot` is the most expensive category to capture - each event carries an encoded image. Enable it only when you need visual snapshots, and prefer [live view](/browsers/live-view) or [replays](/browsers/replays) for continuous visibility. +## Data sensitivity + +Telemetry reflects real activity inside the session, so some categories can carry secrets or personal data. You receive your own session's data, but you should treat the stream - and anywhere you forward or store it - with the same care as the underlying content. + +| Category | Can contain sensitive data | +| --- | --- | +| `console` | Anything the page logs. Applications often log access tokens, request or response bodies, and personal data through `console.log`. | +| `network` | Request and response **URLs, headers (including `Authorization` and cookies), and bodies** - a common place for credentials, session tokens, and personal data. | +| `page` | Page URLs and titles, which can embed tokens or identifiers in query strings or fragments. | +| `interaction` | Text of clicked elements and typed keys, which can include personal data entered into forms. | +| `screenshot` | A full rendered image of the page - the broadest exposure, capturing anything visible on screen. | +| `control`, `connection`, `system`, `captcha`, `monitor` | Session metadata only (control calls, connection and health events). No page content. | + +Some exposure is reduced for you automatically: input into sensitive fields such as passwords is suppressed (`interaction_key` isn't emitted for them, and `interaction_click` omits the element text). Beyond that, because selection is opt-in, the most effective control is to capture only the categories you need - enable `console`, `network`, `page`, `interaction`, or `screenshot` deliberately, and prefer the operational categories when you only need session health. + ## The default set When you enable telemetry without naming any categories (`telemetry: { enabled: true }`, or `--telemetry=all`), the session captures the default set - a lightweight bundle of operational signals: diff --git a/introduction/observe.mdx b/introduction/observe.mdx index 4f22a6e..6f9310f 100644 --- a/introduction/observe.mdx +++ b/introduction/observe.mdx @@ -3,7 +3,7 @@ title: "Observe" description: "Watch your agent work, debug what went wrong" --- -Browser agents fail in ways that don't show up in logs. Kernel gives you four ways to see what's actually happening — live, after the fact, frame by frame, and line by line. +Browser agents fail in ways that don't show up in logs. Kernel gives you several ways to see what's actually happening — live, after the fact, frame by frame, line by line, and event by event. ## Live view @@ -192,9 +192,55 @@ if err := stream.Err(); err != nil { Full reference: [Logs](/apps/logs). +## Telemetry + +Telemetry is a real-time, structured stream of what happens inside a session — console output, network activity, page lifecycle, interactions, and operational signals like crashes. Unlike a video or screenshot, it's machine-readable, so it's the right tool for feeding session activity into your own observability pipeline or reacting to events programmatically. Enable it at creation, then stream the events: + + +```typescript Typescript/Javascript +const browser = await kernel.browsers.create({ telemetry: { enabled: true } }); + +const stream = await kernel.browsers.telemetry.stream(browser.session_id); +for await (const { seq, event } of stream) { + console.log(`#${seq} [${event.category}] ${event.type}`); +} +``` + +```python Python +browser = kernel.browsers.create(telemetry={"enabled": True}) + +with kernel.browsers.telemetry.stream(browser.session_id) as stream: + for envelope in stream: + print(f"#{envelope.seq} [{envelope.event.category}] {envelope.event.type}") +``` + +```go Go +stream := client.Browsers.Telemetry.StreamStreaming( + ctx, + kernelBrowser.SessionID, + kernel.BrowserTelemetryStreamParams{}, +) +defer stream.Close() + +for stream.Next() { + fmt.Println(stream.Current()) +} +if err := stream.Err(); err != nil { + panic(err) +} +``` + +```bash CLI +kernel browsers telemetry stream +``` + + +Full reference: [Telemetry](/browsers/telemetry/overview). + ## Picking the right tool - **Building the agent?** Keep a [live view](/browsers/live-view) tab open while you iterate. - **Debugging a failure?** Capture a [replay](/browsers/replays) for the run, then watch the video. - **Instrumenting the agent itself?** Drop [screenshots](/browsers/computer-controls#take-screenshots) and [logs](/apps/logs) into your traces at the points that matter. +- **Feeding an observability pipeline?** Stream [telemetry](/browsers/telemetry/overview) events and route them wherever you collect signals. - **Putting a human in the loop?** Embed the [live view](/browsers/live-view#embedding-in-an-iframe) in your own UI. From ba4de5b5460122b3c6e4e3513916d4190f3ef5df Mon Sep 17 00:00:00 2001 From: Sayan Samanta Date: Tue, 9 Jun 2026 14:41:43 -0700 Subject: [PATCH 04/13] Sharpen telemetry data-sensitivity section per security discussion Aligns the guide with the team's decision to be upfront about telemetry data types and sensitivity (managed-auth-docs style): - Lead with the default-safe posture (off by default; default set is operational metadata only). - Spell out that the browser-activity categories capture the customer's own browser data, naming network's raw headers (Authorization, Cookie), request bodies, and truncated response bodies explicitly. - Note that captured events persist and are retrievable via the API, so the sensitivity applies at rest, not just in the live stream. - Add guidance for customers under HIPAA/GDPR-style obligations to be deliberate about enabling these categories and to reach out. Co-authored-by: Cursor --- browsers/telemetry/categories.mdx | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/browsers/telemetry/categories.mdx b/browsers/telemetry/categories.mdx index b306328..30d58d8 100644 --- a/browsers/telemetry/categories.mdx +++ b/browsers/telemetry/categories.mdx @@ -40,18 +40,24 @@ These categories report on the session itself rather than page content. They're ## Data sensitivity -Telemetry reflects real activity inside the session, so some categories can carry secrets or personal data. You receive your own session's data, but you should treat the stream - and anywhere you forward or store it - with the same care as the underlying content. +Telemetry is off by default, and the [default set](#the-default-set) carries operational metadata only - no page content. The browser-activity categories are different: they capture what actually flows through the session, which is your own browser's data and can include credentials and personal information. | Category | Can contain sensitive data | | --- | --- | +| `network` | Request and response **headers (including `Authorization` and `Cookie`), request bodies, and truncated response bodies**, plus full URLs. A common place for session tokens, credentials, and personal data. | | `console` | Anything the page logs. Applications often log access tokens, request or response bodies, and personal data through `console.log`. | -| `network` | Request and response **URLs, headers (including `Authorization` and cookies), and bodies** - a common place for credentials, session tokens, and personal data. | | `page` | Page URLs and titles, which can embed tokens or identifiers in query strings or fragments. | | `interaction` | Text of clicked elements and typed keys, which can include personal data entered into forms. | | `screenshot` | A full rendered image of the page - the broadest exposure, capturing anything visible on screen. | | `control`, `connection`, `system`, `captcha`, `monitor` | Session metadata only (control calls, connection and health events). No page content. | -Some exposure is reduced for you automatically: input into sensitive fields such as passwords is suppressed (`interaction_key` isn't emitted for them, and `interaction_click` omits the element text). Beyond that, because selection is opt-in, the most effective control is to capture only the categories you need - enable `console`, `network`, `page`, `interaction`, or `screenshot` deliberately, and prefer the operational categories when you only need session health. +Captured events are stored and retrievable through the API, so this sensitivity applies to the data at rest, not just the live stream. Treat captured telemetry - and anywhere you forward or store it - with the same care as the underlying content. + +Some exposure is reduced for you automatically: input into sensitive fields such as passwords is suppressed (`interaction_key` isn't emitted for them, and `interaction_click` omits the element text). Beyond that, because selection is opt-in, the most effective control is to capture only the categories you need - enable `network`, `console`, `page`, `interaction`, or `screenshot` deliberately, and prefer the operational categories when you only need session health. + + +If you operate under HIPAA, GDPR, or similar obligations, be deliberate about the browser-activity categories: pointing them at a site that handles regulated data captures that data into storage. If you have compliance requirements around what Kernel may process, [contact us](mailto:security@kernel.sh) before enabling them. + ## The default set From d936e2a2d0a0349132ec2250e8cad985849b858f Mon Sep 17 00:00:00 2001 From: Sayan Samanta Date: Tue, 9 Jun 2026 14:47:48 -0700 Subject: [PATCH 05/13] Fix telemetry category grouping and de-duplicate guidance Self-review cleanup of the categories page: - Move screenshot from Operational to Browser activity. It captures page content, attaches the CDP collector, and is the most sensitive and expensive category, so grouping it with operational metadata contradicted the section's own description and the data-sensitivity table. This matches the server taxonomy, where screenshot is a CDP category excluded from the default set. - Fold the standalone "default set" section into Operational, which is now exactly that set, removing a redundant section. - Drop the duplicated sensitive-field suppression sentence from the interaction note; it lives in the data-sensitivity section. - Reference the browser-activity group from the monitor section instead of an inline list that no longer enumerated every triggering category. Co-authored-by: Cursor --- browsers/telemetry/categories.mdx | 26 +++++++++----------------- 1 file changed, 9 insertions(+), 17 deletions(-) diff --git a/browsers/telemetry/categories.mdx b/browsers/telemetry/categories.mdx index 30d58d8..29c0fd0 100644 --- a/browsers/telemetry/categories.mdx +++ b/browsers/telemetry/categories.mdx @@ -17,14 +17,19 @@ These categories report what's happening in the page. Capturing any of them atta | `network` | Network requests, responses, and failures | `network_request`, `network_response`, `network_loading_failed`, `network_idle` | | `page` | Navigation and page lifecycle, including performance signals | `page_navigation`, `page_dom_content_loaded`, `page_load`, `page_tab_opened`, `page_layout_shift`, `page_lcp`, `page_layout_settled`, `page_navigation_settled` | | `interaction` | Browser-native input in the page (clicks, keys, scroll) | `interaction_click`, `interaction_key`, `interaction_scroll_settled` | +| `screenshot` | Periodic screenshots of the session | `monitor_screenshot` | -`interaction` events are browser-native DOM events observed in the page, not calls to the [computer-control](/browsers/computer-controls) API (those are reported by the `control` category). Input into sensitive fields such as passwords is suppressed: `interaction_key` isn't emitted for them, and `interaction_click` omits the element text. +`interaction` events are browser-native DOM events observed in the page, not calls to the [computer-control](/browsers/computer-controls) API (those are reported by the `control` category). + +`screenshot` is the most expensive category to capture - each event carries an encoded image. Enable it only when you need visual snapshots, and prefer [live view](/browsers/live-view) or [replays](/browsers/replays) for continuous visibility. + + ## Operational -These categories report on the session itself rather than page content. They're cheap to capture, and the first four make up the [default set](#the-default-set). +These categories report on the session itself rather than page content, and they're cheap to capture. Together they make up the **default set** - what a session captures when you enable telemetry without naming any categories (`telemetry: { enabled: true }` or `--telemetry=all`), giving you a baseline view of session health and control activity. | Category | Captures | Event types | | --- | --- | --- | @@ -32,15 +37,10 @@ These categories report on the session itself rather than page content. They're | `connection` | CDP and live view connect/disconnect activity | `cdp_connect`, `cdp_disconnect`, `live_view_connect`, `live_view_disconnect` | | `system` | VM-level failures | `system_oom_kill`, `service_crashed` | | `captcha` | Results of automated captcha solves | `captcha_solve_result` | -| `screenshot` | Periodic screenshots of the session | `monitor_screenshot` | - - -`screenshot` is the most expensive category to capture - each event carries an encoded image. Enable it only when you need visual snapshots, and prefer [live view](/browsers/live-view) or [replays](/browsers/replays) for continuous visibility. - ## Data sensitivity -Telemetry is off by default, and the [default set](#the-default-set) carries operational metadata only - no page content. The browser-activity categories are different: they capture what actually flows through the session, which is your own browser's data and can include credentials and personal information. +Telemetry is off by default, and the [default set](#operational) carries operational metadata only - no page content. The browser-activity categories are different: they capture what actually flows through the session, which is your own browser's data and can include credentials and personal information. | Category | Can contain sensitive data | | --- | --- | @@ -59,16 +59,8 @@ Some exposure is reduced for you automatically: input into sensitive fields such If you operate under HIPAA, GDPR, or similar obligations, be deliberate about the browser-activity categories: pointing them at a site that handles regulated data captures that data into storage. If you have compliance requirements around what Kernel may process, [contact us](mailto:security@kernel.sh) before enabling them. -## The default set - -When you enable telemetry without naming any categories (`telemetry: { enabled: true }`, or `--telemetry=all`), the session captures the default set - a lightweight bundle of operational signals: - -`control`, `connection`, `system`, `captcha` - -These are inexpensive to leave on and give you a baseline view of session health and control activity without the volume of the browser-activity categories. - ## The monitor category `monitor` reports the health of the CDP collector itself: `monitor_disconnected`, `monitor_reconnected`, `monitor_reconnect_failed`, and `monitor_init_failed`. -It isn't directly settable. It flows automatically whenever any browser-activity category (`console`, `network`, `page`, `interaction`) is captured - since those are what attach the collector - and is silent otherwise. You can still [filter the stream](/browsers/telemetry/streaming) by `monitor` to isolate these events. +It isn't directly settable. It flows automatically whenever any [browser-activity category](#browser-activity) is captured - since those are what attach the collector - and is silent otherwise. You can still [filter the stream](/browsers/telemetry/streaming) by `monitor` to isolate these events. From 57b96ebbd1f477221ee56bb93c3b1acbbc7bc910 Mon Sep 17 00:00:00 2001 From: Sayan Samanta Date: Tue, 9 Jun 2026 15:11:53 -0700 Subject: [PATCH 06/13] Address persona review: link data-handling, add event example - Link the data-sensitivity section to Security and the DPA for encryption, retention, and processing rather than restating them. - Clarify that browser-activity categories produce far more events than operational ones, and that captured events are replayable via stream resume (not a separate query API). - Add a sample event envelope and document the 1 MB truncation behavior on the streaming page so pipeline builders know what to expect. - Reword "three shapes" to "three ways to configure it". Co-authored-by: Cursor --- browsers/telemetry/categories.mdx | 4 ++-- browsers/telemetry/overview.mdx | 2 +- browsers/telemetry/streaming.mdx | 16 +++++++++++++++- 3 files changed, 18 insertions(+), 4 deletions(-) diff --git a/browsers/telemetry/categories.mdx b/browsers/telemetry/categories.mdx index 29c0fd0..c517705 100644 --- a/browsers/telemetry/categories.mdx +++ b/browsers/telemetry/categories.mdx @@ -9,7 +9,7 @@ For the full payload schema of any event type, see the [Stream telemetry events] ## Browser activity -These categories report what's happening in the page. Capturing any of them attaches a Chrome DevTools Protocol (CDP) collector to the session, so enable only the ones you need. None are in the default set. +These categories report what's happening in the page. Capturing any of them attaches a Chrome DevTools Protocol (CDP) collector to the session and produces far more events than the operational categories, so enable only the ones you need. None are in the default set. | Category | Captures | Event types | | --- | --- | --- | @@ -51,7 +51,7 @@ Telemetry is off by default, and the [default set](#operational) carries operati | `screenshot` | A full rendered image of the page - the broadest exposure, capturing anything visible on screen. | | `control`, `connection`, `system`, `captcha`, `monitor` | Session metadata only (control calls, connection and health events). No page content. | -Captured events are stored and retrievable through the API, so this sensitivity applies to the data at rest, not just the live stream. Treat captured telemetry - and anywhere you forward or store it - with the same care as the underlying content. +Captured events are persisted and can be replayed by [resuming the stream](/browsers/telemetry/streaming#resuming-after-a-disconnect), so this sensitivity applies to the data at rest, not just the live stream. Treat captured telemetry - and anywhere you forward or store it - with the same care as the underlying content. For how Kernel encrypts, retains, and processes data overall, see [Security](/security) and the [Data Processing Addendum](/dpa). Some exposure is reduced for you automatically: input into sensitive fields such as passwords is suppressed (`interaction_key` isn't emitted for them, and `interaction_click` omits the element text). Beyond that, because selection is opt-in, the most effective control is to capture only the categories you need - enable `network`, `console`, `page`, `interaction`, or `screenshot` deliberately, and prefer the operational categories when you only need session health. diff --git a/browsers/telemetry/overview.mdx b/browsers/telemetry/overview.mdx index 9fed2f3..a786212 100644 --- a/browsers/telemetry/overview.mdx +++ b/browsers/telemetry/overview.mdx @@ -13,7 +13,7 @@ Selection is **opt-in**. A session captures a category only if you explicitly tu ## Enabling telemetry -You configure telemetry when you [create a browser](/introduction/create) (and can change it later on update). There are exactly three shapes. +You configure telemetry when you [create a browser](/introduction/create) (and can change it later on update). There are three ways to configure it. ### Enable the default set diff --git a/browsers/telemetry/streaming.mdx b/browsers/telemetry/streaming.mdx index 00469ff..716dd91 100644 --- a/browsers/telemetry/streaming.mdx +++ b/browsers/telemetry/streaming.mdx @@ -3,7 +3,21 @@ title: "Stream Telemetry" description: "Consume a session's live telemetry stream from the SDK, CLI, or raw SSE" --- -Once a session has telemetry [enabled](/browsers/telemetry/overview), you can stream its events in real time. The stream stays open until the session terminates, and each event is wrapped in an envelope with a monotonic `seq` number you can use to reconnect without gaps. +Once a session has telemetry [enabled](/browsers/telemetry/overview), you can stream its events in real time. The stream stays open until the session terminates, and each event is wrapped in an envelope with a monotonic `seq` number you can use to reconnect without gaps: + +```json +{ + "seq": 42, + "event": { + "ts": 1746123456789000, + "type": "network_response", + "category": "network", + "data": { "method": "GET", "url": "https://example.com/api", "status": 200 } + } +} +``` + +The `data` payload differs per event type; see the [API reference](https://kernel.sh/docs/api-reference/browser-telemetry/stream-telemetry-events-via-sse) for each type's schema. An event whose payload exceeds 1 MB is dropped and the envelope is flagged `truncated: true`. ## Via SDK From 633e105eb4ed4ab31fa2762ba5eeef14e5ddc5b7 Mon Sep 17 00:00:00 2001 From: Sayan Samanta Date: Tue, 9 Jun 2026 15:21:56 -0700 Subject: [PATCH 07/13] Trim duplicate envelope description on streaming page The sample envelope now shown in the intro already lists the seq/event fields, so the "Via SDK" sentence no longer needs to repeat them. Co-authored-by: Cursor --- browsers/telemetry/streaming.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/browsers/telemetry/streaming.mdx b/browsers/telemetry/streaming.mdx index 716dd91..33e1b82 100644 --- a/browsers/telemetry/streaming.mdx +++ b/browsers/telemetry/streaming.mdx @@ -21,7 +21,7 @@ The `data` payload differs per event type; see the [API reference](https://kerne ## Via SDK -Open the stream and iterate over it. Each item is an envelope with a `seq` and the `event` itself, which carries a `type`, a `category`, and a `ts` timestamp: +Open the stream and iterate over the envelopes: ```typescript Typescript/Javascript From 4ed983d8ae686f52708b2f82ea533f34c8bf4e4e Mon Sep 17 00:00:00 2001 From: Sayan Samanta Date: Tue, 9 Jun 2026 18:12:17 -0700 Subject: [PATCH 08/13] Remove bold emphasis from telemetry docs Co-authored-by: Cursor --- browsers/telemetry/categories.mdx | 4 ++-- browsers/telemetry/overview.mdx | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/browsers/telemetry/categories.mdx b/browsers/telemetry/categories.mdx index c517705..a7dda98 100644 --- a/browsers/telemetry/categories.mdx +++ b/browsers/telemetry/categories.mdx @@ -29,7 +29,7 @@ These categories report what's happening in the page. Capturing any of them atta ## Operational -These categories report on the session itself rather than page content, and they're cheap to capture. Together they make up the **default set** - what a session captures when you enable telemetry without naming any categories (`telemetry: { enabled: true }` or `--telemetry=all`), giving you a baseline view of session health and control activity. +These categories report on the session itself rather than page content, and they're cheap to capture. Together they make up the default set - what a session captures when you enable telemetry without naming any categories (`telemetry: { enabled: true }` or `--telemetry=all`), giving you a baseline view of session health and control activity. | Category | Captures | Event types | | --- | --- | --- | @@ -44,7 +44,7 @@ Telemetry is off by default, and the [default set](#operational) carries operati | Category | Can contain sensitive data | | --- | --- | -| `network` | Request and response **headers (including `Authorization` and `Cookie`), request bodies, and truncated response bodies**, plus full URLs. A common place for session tokens, credentials, and personal data. | +| `network` | Request and response headers (including `Authorization` and `Cookie`), request bodies, and truncated response bodies, plus full URLs. A common place for session tokens, credentials, and personal data. | | `console` | Anything the page logs. Applications often log access tokens, request or response bodies, and personal data through `console.log`. | | `page` | Page URLs and titles, which can embed tokens or identifiers in query strings or fragments. | | `interaction` | Text of clicked elements and typed keys, which can include personal data entered into forms. | diff --git a/browsers/telemetry/overview.mdx b/browsers/telemetry/overview.mdx index a786212..51e58c1 100644 --- a/browsers/telemetry/overview.mdx +++ b/browsers/telemetry/overview.mdx @@ -7,9 +7,9 @@ Telemetry gives you a real-time stream of events from inside a browser session - ## The model -Every telemetry event belongs to a **category** (`console`, `network`, `page`, and so on). Categories are the unit of control: you choose which categories a session captures, and the stream only carries events from those categories. +Every telemetry event belongs to a category (`console`, `network`, `page`, and so on). Categories are the unit of control: you choose which categories a session captures, and the stream only carries events from those categories. -Selection is **opt-in**. A session captures a category only if you explicitly turn it on; anything you don't list stays off. See [Categories](/browsers/telemetry/categories) for the full list, what each one captures, and its cost. +Selection is opt-in. A session captures a category only if you explicitly turn it on; anything you don't list stays off. See [Categories](/browsers/telemetry/categories) for the full list, what each one captures, and its cost. ## Enabling telemetry @@ -102,7 +102,7 @@ kernel browsers create --telemetry=off -Updating a session's telemetry **replaces** its category selection - it isn't merged with the previous one. Send the complete set of categories you want captured. +Updating a session's telemetry replaces its category selection - it isn't merged with the previous one. Send the complete set of categories you want captured. ## What's next From 9c4c6be5cbfbcad6227d8986314391eb0048f3e0 Mon Sep 17 00:00:00 2001 From: Sayan Samanta Date: Tue, 9 Jun 2026 18:13:29 -0700 Subject: [PATCH 09/13] Reframe telemetry overview intro around capturing events Co-authored-by: Cursor --- browsers/telemetry/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/browsers/telemetry/overview.mdx b/browsers/telemetry/overview.mdx index 51e58c1..13bedf7 100644 --- a/browsers/telemetry/overview.mdx +++ b/browsers/telemetry/overview.mdx @@ -3,7 +3,7 @@ title: "Telemetry Overview" description: "Capture a real-time, categorized stream of what happens inside a browser session" --- -Telemetry gives you a real-time stream of events from inside a browser session - console output, network activity, page lifecycle, user interactions, captcha solves, and operational signals like crashes or connection changes. Events are delivered over [Server-Sent Events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events), so you can react to them live or pipe them into your own observability stack. +Telemetry captures events from inside a browser session - console output, network activity, page lifecycle, user interactions, captcha solves, and operational signals like crashes or connection changes. You choose which categories of events a session records; once enabled, you can [stream them](/browsers/telemetry/streaming) live or feed them into your own observability stack. ## The model From 72bbeadfd968ce9b3a4b1ab68be382b3ae538d16 Mon Sep 17 00:00:00 2001 From: Sayan Samanta Date: Tue, 9 Jun 2026 18:15:43 -0700 Subject: [PATCH 10/13] Tighten telemetry overview intro into one concept paragraph Co-authored-by: Cursor --- browsers/telemetry/overview.mdx | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/browsers/telemetry/overview.mdx b/browsers/telemetry/overview.mdx index 13bedf7..b7f2e34 100644 --- a/browsers/telemetry/overview.mdx +++ b/browsers/telemetry/overview.mdx @@ -3,13 +3,9 @@ title: "Telemetry Overview" description: "Capture a real-time, categorized stream of what happens inside a browser session" --- -Telemetry captures events from inside a browser session - console output, network activity, page lifecycle, user interactions, captcha solves, and operational signals like crashes or connection changes. You choose which categories of events a session records; once enabled, you can [stream them](/browsers/telemetry/streaming) live or feed them into your own observability stack. +Telemetry captures events from inside a browser session - console output, network activity, page lifecycle, user interactions, captcha solves, and operational signals like crashes or connection changes. You choose which categories of events a session records; once enabled, you can [stream them](/browsers/telemetry/streaming) live or pull them later for analysis. -## The model - -Every telemetry event belongs to a category (`console`, `network`, `page`, and so on). Categories are the unit of control: you choose which categories a session captures, and the stream only carries events from those categories. - -Selection is opt-in. A session captures a category only if you explicitly turn it on; anything you don't list stays off. See [Categories](/browsers/telemetry/categories) for the full list, what each one captures, and its cost. +Events are grouped into categories (`console`, `network`, `page`, and so on), and categories are the unit of control. Selection is opt-in: a session captures only the categories you turn on, and anything you don't stays off. See [Categories](/browsers/telemetry/categories) for the full list, what each one captures, and its cost. ## Enabling telemetry From 7f2ec0e89b4b94159940fb93bc0d29bf75ae106a Mon Sep 17 00:00:00 2001 From: Sayan Samanta Date: Tue, 9 Jun 2026 18:18:31 -0700 Subject: [PATCH 11/13] Drop duplicate category mention from telemetry intro Co-authored-by: Cursor --- browsers/telemetry/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/browsers/telemetry/overview.mdx b/browsers/telemetry/overview.mdx index b7f2e34..7b3d41a 100644 --- a/browsers/telemetry/overview.mdx +++ b/browsers/telemetry/overview.mdx @@ -3,7 +3,7 @@ title: "Telemetry Overview" description: "Capture a real-time, categorized stream of what happens inside a browser session" --- -Telemetry captures events from inside a browser session - console output, network activity, page lifecycle, user interactions, captcha solves, and operational signals like crashes or connection changes. You choose which categories of events a session records; once enabled, you can [stream them](/browsers/telemetry/streaming) live or pull them later for analysis. +Telemetry captures events from inside a browser session - console output, network activity, page lifecycle, user interactions, captcha solves, and operational signals like crashes or connection changes. Once enabled, you can [stream them](/browsers/telemetry/streaming) live or pull them later for analysis. Events are grouped into categories (`console`, `network`, `page`, and so on), and categories are the unit of control. Selection is opt-in: a session captures only the categories you turn on, and anything you don't stays off. See [Categories](/browsers/telemetry/categories) for the full list, what each one captures, and its cost. From 38c16e5db41aa927b7d5446b722d7d97f8abe8fc Mon Sep 17 00:00:00 2001 From: Sayan Samanta Date: Tue, 9 Jun 2026 18:25:47 -0700 Subject: [PATCH 12/13] Correct telemetry update semantics in docs A per-category update merges into the session's current selection (PATCH semantics, enforced by TestResolveTelemetryConfigUpdateCategoryPatchMerges CurrentConfig); only enabled:true / --telemetry=all resets it. The docs and CLI reference incorrectly described all updates as a replace. Co-authored-by: Cursor --- browsers/telemetry/overview.mdx | 4 ++-- reference/cli/browsers.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/browsers/telemetry/overview.mdx b/browsers/telemetry/overview.mdx index 7b3d41a..3aa40ea 100644 --- a/browsers/telemetry/overview.mdx +++ b/browsers/telemetry/overview.mdx @@ -5,7 +5,7 @@ description: "Capture a real-time, categorized stream of what happens inside a b Telemetry captures events from inside a browser session - console output, network activity, page lifecycle, user interactions, captcha solves, and operational signals like crashes or connection changes. Once enabled, you can [stream them](/browsers/telemetry/streaming) live or pull them later for analysis. -Events are grouped into categories (`console`, `network`, `page`, and so on), and categories are the unit of control. Selection is opt-in: a session captures only the categories you turn on, and anything you don't stays off. See [Categories](/browsers/telemetry/categories) for the full list, what each one captures, and its cost. +Events are grouped into categories (`console`, `network`, `page`, and so on), and categories are the unit of control. Selection is opt-in: a session captures only the categories you turn on, and anything you don't stays off. See [Categories](/browsers/telemetry/categories) for the full list and what each one captures. ## Enabling telemetry @@ -98,7 +98,7 @@ kernel browsers create --telemetry=off -Updating a session's telemetry replaces its category selection - it isn't merged with the previous one. Send the complete set of categories you want captured. +On update, a category list patches the current selection - categories you don't include keep their current state. To reset the selection instead, send `enabled: true` (it replaces the selection with the categories you provide, or the default set if you provide none); send `enabled: false` to turn telemetry off. ## What's next diff --git a/reference/cli/browsers.mdx b/reference/cli/browsers.mdx index 359e597..61db5ba 100644 --- a/reference/cli/browsers.mdx +++ b/reference/cli/browsers.mdx @@ -58,7 +58,7 @@ Update a running browser session — change or remove its proxy, load a profile, | `--save-changes` | Save changes back to the profile when the session ends. | | `--viewport ` | Set viewport size (e.g. `1920x1080@25`). | | `--force` | Force a viewport resize even during an active live view or recording. | -| `--telemetry ` | Configure [telemetry](/browsers/telemetry/overview) (opt-in, replaces the current selection): `all` for the default set, `off` to disable, or a comma-separated category list like `console,network`. | +| `--telemetry ` | Update [telemetry](/browsers/telemetry/overview): `all` resets to the default set, `off` disables, or a comma-separated list like `console,network` to merge those categories into the current selection. | | `--output json`, `-o json` | Output raw API response as JSON. | ### `kernel browsers curl ` From ee78dc07546626ea1bd3c9cdc97e02f826f66dde Mon Sep 17 00:00:00 2001 From: Sayan Samanta Date: Tue, 9 Jun 2026 18:57:46 -0700 Subject: [PATCH 13/13] ai gonna ai --- browsers/telemetry/categories.mdx | 38 ++++++++++++-------------- browsers/telemetry/overview.mdx | 19 +++++++------ browsers/telemetry/streaming.mdx | 45 +++++++------------------------ introduction/observe.mdx | 8 +++--- 4 files changed, 42 insertions(+), 68 deletions(-) diff --git a/browsers/telemetry/categories.mdx b/browsers/telemetry/categories.mdx index a7dda98..88352f1 100644 --- a/browsers/telemetry/categories.mdx +++ b/browsers/telemetry/categories.mdx @@ -3,13 +3,24 @@ title: "Telemetry Categories" description: "The categories a browser session can capture, what each contains, and their cost" --- -A category groups related telemetry events and is the unit you enable or disable. Selection is opt-in: a session captures a category only when you turn it on (see [Overview](/browsers/telemetry/overview)). This page lists every category, the event types it carries, and what it costs to capture. +A category groups related telemetry events and is the unit you enable or disable. Selection is opt-in: a session captures a category only when you turn it on. For the full payload schema of any event type, see the [Stream telemetry events](https://kernel.sh/docs/api-reference/browser-telemetry/stream-telemetry-events-via-sse) endpoint in the API reference. +## Operational + +These categories report on the session itself rather than page content. + +| Category | Captures | Event types | +| --- | --- | --- | +| `control` | Computer-control API calls against the session | `api_call` | +| `connection` | CDP and live view connect/disconnect activity | `cdp_connect`, `cdp_disconnect`, `live_view_connect`, `live_view_disconnect` | +| `system` | VM-level failures | `system_oom_kill`, `service_crashed` | +| `captcha` | Results of automated captcha solves | `captcha_solve_result` | + ## Browser activity -These categories report what's happening in the page. Capturing any of them attaches a Chrome DevTools Protocol (CDP) collector to the session and produces far more events than the operational categories, so enable only the ones you need. None are in the default set. +These categories report what's happening in the page. Capturing any of them attaches a Chrome DevTools Protocol (CDP) collector to the session and produces highly granular page-level events. Capturing them adds overhead, so enable only the ones you need. | Category | Captures | Event types | | --- | --- | --- | @@ -23,24 +34,15 @@ These categories report what's happening in the page. Capturing any of them atta `interaction` events are browser-native DOM events observed in the page, not calls to the [computer-control](/browsers/computer-controls) API (those are reported by the `control` category). - -`screenshot` is the most expensive category to capture - each event carries an encoded image. Enable it only when you need visual snapshots, and prefer [live view](/browsers/live-view) or [replays](/browsers/replays) for continuous visibility. - +### The monitor category -## Operational - -These categories report on the session itself rather than page content, and they're cheap to capture. Together they make up the default set - what a session captures when you enable telemetry without naming any categories (`telemetry: { enabled: true }` or `--telemetry=all`), giving you a baseline view of session health and control activity. +`monitor` reports the health of the CDP collector itself: `monitor_disconnected`, `monitor_reconnected`, `monitor_reconnect_failed`, and `monitor_init_failed`. -| Category | Captures | Event types | -| --- | --- | --- | -| `control` | Computer-control API calls against the session | `api_call` | -| `connection` | CDP and live view connect/disconnect activity | `cdp_connect`, `cdp_disconnect`, `live_view_connect`, `live_view_disconnect` | -| `system` | VM-level failures | `system_oom_kill`, `service_crashed` | -| `captcha` | Results of automated captcha solves | `captcha_solve_result` | +It isn't directly settable. It flows automatically whenever any of the browser-activity categories are captured. You can still [filter the stream](/browsers/telemetry/streaming) by `monitor` to isolate these events. ## Data sensitivity -Telemetry is off by default, and the [default set](#operational) carries operational metadata only - no page content. The browser-activity categories are different: they capture what actually flows through the session, which is your own browser's data and can include credentials and personal information. +Telemetry is off by default and the default set carries operational metadata only. The browser-activity categories are different: they capture what actually flows through the session, which is your own browser's data and can include credentials and personal information. | Category | Can contain sensitive data | | --- | --- | @@ -58,9 +60,3 @@ Some exposure is reduced for you automatically: input into sensitive fields such If you operate under HIPAA, GDPR, or similar obligations, be deliberate about the browser-activity categories: pointing them at a site that handles regulated data captures that data into storage. If you have compliance requirements around what Kernel may process, [contact us](mailto:security@kernel.sh) before enabling them. - -## The monitor category - -`monitor` reports the health of the CDP collector itself: `monitor_disconnected`, `monitor_reconnected`, `monitor_reconnect_failed`, and `monitor_init_failed`. - -It isn't directly settable. It flows automatically whenever any [browser-activity category](#browser-activity) is captured - since those are what attach the collector - and is silent otherwise. You can still [filter the stream](/browsers/telemetry/streaming) by `monitor` to isolate these events. diff --git a/browsers/telemetry/overview.mdx b/browsers/telemetry/overview.mdx index 3aa40ea..7cb2371 100644 --- a/browsers/telemetry/overview.mdx +++ b/browsers/telemetry/overview.mdx @@ -1,6 +1,6 @@ --- title: "Telemetry Overview" -description: "Capture a real-time, categorized stream of what happens inside a browser session" +description: "Capture what happens inside a browser session" --- Telemetry captures events from inside a browser session - console output, network activity, page lifecycle, user interactions, captcha solves, and operational signals like crashes or connection changes. Once enabled, you can [stream them](/browsers/telemetry/streaming) live or pull them later for analysis. @@ -43,7 +43,7 @@ kernel browsers create --telemetry=all ### Capture specific categories -List exactly the categories you want under `telemetry.browser`. Only those are captured; everything else stays off. Don't set the top-level `enabled` flag in this case - the presence of category settings is what turns telemetry on: +List the categories you want under `telemetry.browser`. For example, this session captures `console` and `network` only: ```typescript Typescript/Javascript @@ -73,27 +73,30 @@ kernel browsers create --telemetry=console,network ``` -This session captures `console` and `network` only - no page, interaction, or operational events. - ### Disable telemetry -Set `enabled: false` to capture nothing. This can't be combined with category settings: + +Telemetry is disabled by default. Use this only when updating a session to turn previously enabled telemetry back off. + + +Set `enabled: false` on an existing session to turn telemetry off: ```typescript Typescript/Javascript -const browser = await kernel.browsers.create({ +await kernel.browsers.update(browser.session_id, { telemetry: { enabled: false }, }); ``` ```python Python -browser = kernel.browsers.create( +kernel.browsers.update( + browser.session_id, telemetry={"enabled": False}, ) ``` ```bash CLI -kernel browsers create --telemetry=off +kernel browsers update --telemetry=off ``` diff --git a/browsers/telemetry/streaming.mdx b/browsers/telemetry/streaming.mdx index 33e1b82..5f064ad 100644 --- a/browsers/telemetry/streaming.mdx +++ b/browsers/telemetry/streaming.mdx @@ -1,23 +1,9 @@ --- title: "Stream Telemetry" -description: "Consume a session's live telemetry stream from the SDK, CLI, or raw SSE" +description: "Consume a session's live telemetry stream from the SDK or CLI" --- -Once a session has telemetry [enabled](/browsers/telemetry/overview), you can stream its events in real time. The stream stays open until the session terminates, and each event is wrapped in an envelope with a monotonic `seq` number you can use to reconnect without gaps: - -```json -{ - "seq": 42, - "event": { - "ts": 1746123456789000, - "type": "network_response", - "category": "network", - "data": { "method": "GET", "url": "https://example.com/api", "status": 200 } - } -} -``` - -The `data` payload differs per event type; see the [API reference](https://kernel.sh/docs/api-reference/browser-telemetry/stream-telemetry-events-via-sse) for each type's schema. An event whose payload exceeds 1 MB is dropped and the envelope is flagged `truncated: true`. +Once a session has telemetry [enabled](/browsers/telemetry/overview), you can stream its events in real time. The stream stays open until the session terminates. ## Via SDK @@ -48,6 +34,8 @@ with kernel.browsers.telemetry.stream(session_id) as stream: ``` +To filter, check `event.category` and `event.type` in your loop. If the stream drops, re-open it with the last `seq` you processed as `last_event_id` to resume without gaps. + ## Via CLI Stream events to your terminal. The command runs until the session ends or you interrupt it: @@ -56,7 +44,7 @@ Stream events to your terminal. The command runs until the session ends or you i kernel browsers telemetry stream ``` -Filter the stream client-side by category or event type (repeatable or comma-separated), and use `-o json` to emit newline-delimited JSON envelopes for piping: +### Filtering by category or event type ```bash # Only network and console events @@ -66,29 +54,16 @@ kernel browsers telemetry stream --categories=network,console kernel browsers telemetry stream --types=network_response,console_error # Machine-readable output +# -o json emits newline-delimited JSON envelopes for piping: kernel browsers telemetry stream -o json ``` - -CLI `--categories` and `--types` are applied locally to the stream - they don't change what the session captures. To change capture, update the session's [telemetry categories](/browsers/telemetry/categories). - - -## Via raw SSE - -The stream is a standard [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) endpoint, so any SSE-capable client works: - -```bash -curl -N https://api.onkernel.com/browsers//telemetry/stream \ - -H "Authorization: Bearer $KERNEL_API_KEY" \ - -H "Accept: text/event-stream" -``` - -Each `data:` frame carries one JSON envelope, and the frame's `id:` field is the envelope's `seq`. A keepalive comment is sent every 15 seconds when no events arrive. The `event:` field is never set. - -## Resuming after a disconnect +### Resuming after a disconnect -To pick up where you left off, resume from the last `seq` you processed - the server replays events after that sequence number. SDK clients reconnect automatically. For raw SSE, send the last seq as the `Last-Event-ID` header; with the CLI, pass `--seq`: +The stream is a single connection; it does not reconnect on its own. Each event carries a monotonic `seq`, so to resume without gaps you re-open the stream and pass the last `seq` you processed. ```bash kernel browsers telemetry stream --seq 1024 ``` + +The server then replays events after that sequence number. diff --git a/introduction/observe.mdx b/introduction/observe.mdx index 6f9310f..1ae528f 100644 --- a/introduction/observe.mdx +++ b/introduction/observe.mdx @@ -3,7 +3,7 @@ title: "Observe" description: "Watch your agent work, debug what went wrong" --- -Browser agents fail in ways that don't show up in logs. Kernel gives you several ways to see what's actually happening — live, after the fact, frame by frame, line by line, and event by event. +Browser agents fail in ways that don't show up in logs. Kernel gives you several ways to see what's actually happening: live, after the fact, frame by frame, line by line, and event by event. ## Live view @@ -60,7 +60,7 @@ Add `?readOnly=true` for a non-interactive view, or enable [kiosk mode](/browser ## Replays -Replays are MP4 recordings you start and stop on demand — capture as many clips per session as you need. They're the right tool for post-hoc debugging: a failed run gives you one or more videos to scrub through, share, or attach to a bug report. +Replays are MP4 recordings you start and stop on demand - capture as many clips per session as you need. They're the right tool for post-hoc debugging: a failed run gives you one or more videos to scrub through, share, or attach to a bug report. Replays can also be enabled on managed auth sessions, so you can [debug failed logins](https://www.kernel.sh/docs/auth/configuration#record-sessions-for-debugging) the same way. @@ -119,7 +119,7 @@ Full reference: [Replays](/browsers/replays). ## Screenshots -Pull a frame at any moment with computer controls — useful for snapshotting state at decision points, attaching to traces, or feeding back into a vision model. +Pull a frame at any moment with computer controls - useful for snapshotting state at decision points, attaching to traces, or feeding back into a vision model. ```typescript Typescript/Javascript @@ -194,7 +194,7 @@ Full reference: [Logs](/apps/logs). ## Telemetry -Telemetry is a real-time, structured stream of what happens inside a session — console output, network activity, page lifecycle, interactions, and operational signals like crashes. Unlike a video or screenshot, it's machine-readable, so it's the right tool for feeding session activity into your own observability pipeline or reacting to events programmatically. Enable it at creation, then stream the events: +Telemetry is a real-time, structured stream of what happens inside a session: console output, network activity, page lifecycle, interactions, and operational signals like crashes. Unlike a video or screenshot, it's machine-readable, so it's the right tool for feeding session activity into your own observability pipeline or reacting to events programmatically. Enable it at creation, then stream the events: ```typescript Typescript/Javascript