ai gonna ai

Author: Sayan-

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).
 </Note>
 
-<Warning>
-`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.
-</Warning>
+### 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
 <Warning>
 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.
 </Warning>
-
-## 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.

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:
 
 <CodeGroup>
 ```typescript Typescript/Javascript
@@ -73,27 +73,30 @@ kernel browsers create --telemetry=console,network
 ```
 </CodeGroup>
 
-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:
+<Info>
+Telemetry is disabled by default. Use this only when updating a session to turn previously enabled telemetry back off.
+</Info>
+
+Set `enabled: false` on an existing session to turn telemetry off:
 
 <CodeGroup>
 ```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 <session-id> --telemetry=off
 ```
 </CodeGroup>
 

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:
 ```
 </CodeGroup>
 
+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 <session-id>
 ```
 
-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 <session-id> --categories=network,console
 kernel browsers telemetry stream <session-id> --types=network_response,console_error
 
 # Machine-readable output
+# -o json emits newline-delimited JSON envelopes for piping:
 kernel browsers telemetry stream <session-id> -o json
 ```
 
-<Info>
-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).
-</Info>
-
-## 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/<session-id>/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 <session-id> --seq 1024
 ```
+
+The server then replays events after that sequence number.

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.
 
 <CodeGroup>
 ```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:
 
 <CodeGroup>
 ```typescript Typescript/Javascript