Add browser telemetry guide by ehfeng · Pull Request #384 · kernel/docs

ehfeng · 2026-05-28T16:37:22Z

Summary

Adds browsers/telemetry.mdx — a full guide for the SSE-based browser telemetry stream covering enabling capture, consuming events, per-category configuration (console, network, page, interaction), reconnection via Last-Event-ID, updating config on running sessions, and the event envelope schema
Adds telemetry to the sidebar nav under Working with your browser > Basics
Updates introduction/observe.mdx with a browser telemetry section and quick-start example

Test plan

mintlify dev renders the new page correctly
All internal links resolve (telemetry from observe, observe from telemetry)
Code examples in TypeScript and Python are syntactically correct
Event type tables render properly

🤖 Generated with Claude Code

Note

Low Risk
Documentation-only changes with no runtime, API, or auth code modifications.

Overview
Adds a Browser Telemetry guide (browsers/telemetry.mdx) documenting SSE streaming of console, network, page, interaction, and system events: enable/disable and per-category config at create and via PATCH, consuming the stream (SDK, HTTP, CLI), reconnection with Last-Event-ID, and the event envelope plus type-specific payloads.

Wires the feature into the docs site: nav entry under Working with your browser → Basics, a new Browser telemetry section and “picking the right tool” bullet on Observe, and CLI reference for --telemetry on create/update and kernel browsers telemetry stream (filters, --seq, NDJSON output).

^{Reviewed by Cursor Bugbot for commit ff8f5cb. Bugbot is set up for automated code reviews on this repo. Configure here.}

Documents the SSE-based browser telemetry stream — enabling capture, consuming events, per-category configuration, reconnection, and the full event type reference across console, network, page, interaction, and monitor categories. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

firetiger-agent · 2026-05-28T16:37:41Z

Firetiger deploy monitoring skipped

This PR didn't match the auto-monitor filter configured on your GitHub connection:

Any PR that changes the kernel API. Monitor changes to API endpoints (packages/api/cmd/api/) and Temporal workflows (packages/api/lib/temporal) in the kernel repo

Reason: PR only adds documentation (MDX files) with no changes to API endpoints or Temporal workflows.

To monitor this PR anyway, reply with @firetiger monitor this.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7ca465dd5e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-28T16:40:20Z

+<CodeGroup>
+```typescript Typescript/Javascript
+const response = await fetch(
+  `https://api.onkernel.com/v1/browsers/${kernelBrowser.session_id}/telemetry`,


Use the unversioned browser endpoint

When a user copies this SSE URL, it points at https://api.onkernel.com/v1/browsers/..., but the Kernel API reference and existing raw HTTP examples in this repo use the unversioned https://api.onkernel.com/browsers/... path (PATCH /browsers/{id}, GET /browsers/{id}, and the project-scoping curl example). This same /v1 prefix is repeated in the Python, observe, and reconnect examples, so users following the guide will likely hit a 404 instead of opening the telemetry stream unless the URL is changed to the documented base path.

Useful? React with 👍 / 👎.

mintlify · 2026-05-28T16:48:37Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Kernel	🟢 Ready	View Preview	May 28, 2026, 4:49 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

- Add CLI examples (create, update, telemetry stream) to all code blocks - Document computed event heuristics (network_idle 500ms, layout_settled 1s) - Add interaction rate-limiting (20/s) and sensitive input suppression - Improve monitor event descriptions (screenshot triggers, reconnect details) - Add event context fields table for cross-tab/navigation correlation - Add telemetry commands to CLI reference (create --telemetry, update, stream) - Restructure event envelope as a table with source.kind descriptions Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

cursor

Stale comment

Risk assessment: Very Low

Evidence from the current diff: this PR only adds and updates documentation content (browsers/telemetry.mdx, introduction/observe.mdx, reference/cli/browsers.mdx) plus one Mintlify navigation entry in docs.json. The synchronize update adds CLI examples/reference details and telemetry guide clarifications, but still does not modify production code, infrastructure, auth/permissions, data schemas, prompts used by models, or shared runtime logic.

I found no CODEOWNERS file requiring owner review. The PR is already approved, so I’m not submitting another approval; the risk level has not increased, so the existing approval can remain.

_{Sent by Cursor Automation: Assign PR reviewers}

cursor

Stale comment

Risk assessment: Very Low

Evidence from the current diff: this PR adds browsers/telemetry.mdx, updates introduction/observe.mdx and reference/cli/browsers.mdx, and adds one Mintlify navigation entry in docs.json. These are documentation and docs-navigation changes only, with no production code, infrastructure, auth/permissions, data schema, shared runtime logic, or model prompt/instruction changes.

I found no CODEOWNERS file requiring owner review. The PR is already approved, so I’m not submitting another approval. The risk has not increased, so the existing approval can remain.

_{Sent by Cursor Automation: Assign PR reviewers}

- Rename "Event categories" to "Event types" - Rename "Event envelope" to "Event body" - Add event.data field tables for all 22 event types - Expand shared context fields (add target_type, loader_id) - Replace em dashes with hyphens throughout Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

cursor

Stale comment

Risk assessment: Very Low

Evidence from the current diff: this PR adds browsers/telemetry.mdx, updates introduction/observe.mdx and reference/cli/browsers.mdx, and adds one Mintlify navigation entry in docs.json. These are documentation and docs-navigation changes only, with no production code, infrastructure, auth/permissions, data schema, shared runtime logic, or model prompt/instruction changes.

I found no CODEOWNERS file requiring owner review. The PR is already approved, so I’m not submitting another approval. The synchronized changes do not increase risk, so the existing approval can remain.

_{Sent by Cursor Automation: Assign PR reviewers}

cursor

Stale comment

Risk assessment: Very Low

Evidence from the current diff: this PR adds browsers/telemetry.mdx, updates introduction/observe.mdx and reference/cli/browsers.mdx, and adds one Mintlify navigation entry in docs.json. These are documentation and docs-navigation changes only, with no production code, infrastructure, auth/permissions, data schema, shared runtime logic, or model prompt/instruction changes.

I found no CODEOWNERS file requiring owner review. The PR is already approved, so I’m not submitting another approval. The synchronized changes do not increase risk, so the existing approval can remain.

_{Sent by Cursor Automation: Assign PR reviewers}

dprevoznik

Left some comments!

- Replace raw HTTP reconnect example with TS/Python/CLI examples - Clarify interaction events are browser-native DOM events, not computer controls API calls - Reorder sections: Reconnecting > Updating telemetry > Event body > Event types Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

cursor

Stale comment

Risk assessment: Very Low

Evidence from the current diff: this PR only adds and updates Mintlify documentation content (browsers/telemetry.mdx, introduction/observe.mdx, reference/cli/browsers.mdx) plus one docs navigation entry in docs.json. It doesn’t modify production code, infrastructure, auth/permissions, data schemas, shared runtime logic, or model prompt/instruction files.

I found no CODEOWNERS file requiring owner review. The PR already has an approval, so I’m not submitting another approval. The synchronized changes don’t increase risk, so I’m not dismissing the existing approval.

_{Sent by Cursor Automation: Assign PR reviewers}

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

cursor

Stale comment

Risk assessment: Very Low

Evidence from the current diff: this PR only adds and updates Mintlify documentation content (browsers/telemetry.mdx, introduction/observe.mdx, reference/cli/browsers.mdx) plus one docs navigation entry in docs.json. It doesn't modify production code, infrastructure, auth/permissions, data schemas, shared runtime logic, or model prompt/instruction files.

I found no CODEOWNERS file in the PR head, so I don't see a codeowner review requirement from the repo contents. The PR already has a Cursor approval, so I'm not submitting another approval. The synchronized changes don't increase risk, so I'm not dismissing the existing approval.

_{Sent by Cursor Automation: Assign PR reviewers}

- Add system_oom_kill and service_crashed event types with data schemas - Rename Monitor section to System to match category name - Add category field to event body spec and JSON example - Fix --seq to document >= 1 (0 is rejected) - List valid --categories values, note invalid ones are rejected Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

cursor

Risk assessment: Very Low

Evidence from the current diff: this PR adds a new Mintlify documentation page (browsers/telemetry.mdx), adds one docs navigation entry in docs.json, and updates related documentation in introduction/observe.mdx and reference/cli/browsers.mdx. It doesn't modify production code, runtime behavior, infrastructure, auth/permissions, data schemas, shared libraries, or model prompt/instruction files.

I found no CODEOWNERS file in the repository contents, so I don't see a codeowner review requirement from the diff/repo structure. This PR already has an earlier cursor[bot] approval, and the current changes don't increase risk, so I'm not submitting a duplicate approval or dismissing the existing one.

_{Sent by Cursor Automation: Assign PR reviewers}

Sayan-

The how-to flow here reads well. My one structural suggestion: the per-event field tables repeat the event schemas we already define in our OpenAPI spec (and ship as typed models in the SDKs), so they'll inevitably drift as events change. I'd keep this page focused on concepts, how-to, and a few example events, and point readers to the SDK types / API reference for the full per-event field details.

Sayan- · 2026-06-09T18:32:29Z

Superseded by #406. The telemetry feature shipped with opt-in category semantics (KERNEL-1342), which inverts the model this PR documents (it predates the realignment — e.g. "omitted categories default to enabled" is now the opposite, and the per-category =on/=off CLI grammar was removed). #406 rewrites the guide from scratch against the shipped behavior as a Telemetry subgroup (overview / categories / streaming), and defers event payload schemas to the generated API reference instead of inlining them. Thanks for the original draft — its structure and SSE-consumption framing carried over.

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 <cursoragent@cursor.com>

* 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 <cursoragent@cursor.com> * 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 <cursoragent@cursor.com> * 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 <cursoragent@cursor.com> * 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 <cursoragent@cursor.com> * 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 <cursoragent@cursor.com> * 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 <cursoragent@cursor.com> * 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 <cursoragent@cursor.com> * Remove bold emphasis from telemetry docs Co-authored-by: Cursor <cursoragent@cursor.com> * Reframe telemetry overview intro around capturing events Co-authored-by: Cursor <cursoragent@cursor.com> * Tighten telemetry overview intro into one concept paragraph Co-authored-by: Cursor <cursoragent@cursor.com> * Drop duplicate category mention from telemetry intro Co-authored-by: Cursor <cursoragent@cursor.com> * 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 <cursoragent@cursor.com> * ai gonna ai --------- Co-authored-by: Cursor <cursoragent@cursor.com>

chatgpt-codex-connector Bot reviewed May 28, 2026

View reviewed changes

mintlify Bot deployed to staging May 28, 2026 16:49 View deployment

cursor Bot approved these changes May 28, 2026 •

edited

Loading

View reviewed changes

mintlify Bot deployed to staging May 28, 2026 17:24 View deployment

cursor Bot reviewed May 28, 2026

View reviewed changes

ehfeng closed this May 28, 2026

archandatta reopened this May 28, 2026

cursor Bot reviewed May 28, 2026

View reviewed changes

mintlify Bot deployed to staging May 29, 2026 11:59 View deployment

archandatta self-requested a review May 29, 2026 12:00

cursor Bot reviewed May 29, 2026

View reviewed changes

Merge branch 'main' into docs/browser-telemetry-guide

604b21b

mintlify Bot deployed to staging May 29, 2026 12:03 View deployment

cursor Bot reviewed May 29, 2026

View reviewed changes

archandatta requested a review from dprevoznik May 29, 2026 12:06

dprevoznik reviewed May 29, 2026

View reviewed changes

Comment thread browsers/telemetry.mdx Outdated

dprevoznik reviewed May 29, 2026

View reviewed changes

Comment thread browsers/telemetry.mdx Outdated

dprevoznik reviewed May 29, 2026

View reviewed changes

Comment thread browsers/telemetry.mdx Outdated

dprevoznik requested changes May 29, 2026

View reviewed changes

mintlify Bot deployed to staging May 29, 2026 14:22 View deployment

dprevoznik reviewed May 29, 2026

View reviewed changes

Comment thread introduction/observe.mdx

cursor Bot reviewed May 29, 2026

View reviewed changes

Move browser telemetry above invocation logs on observe page

32464f4

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

mintlify Bot deployed to staging May 29, 2026 14:32 View deployment

cursor Bot reviewed May 29, 2026

View reviewed changes

archandatta requested a review from dprevoznik May 29, 2026 17:07

Sayan- mentioned this pull request Jun 3, 2026

Rework telemetry event categories kernel/kernel-images#268

Merged

3 tasks

mintlify Bot deployed to staging June 3, 2026 12:22 View deployment

cursor Bot reviewed Jun 3, 2026

View reviewed changes

archandatta requested a review from Sayan- June 3, 2026 12:25

Sayan- reviewed Jun 3, 2026

View reviewed changes

Sayan- mentioned this pull request Jun 9, 2026

Add browser telemetry guide #406

Merged

Sayan- closed this Jun 9, 2026

Conversation

ehfeng commented May 28, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

firetiger-agent Bot commented May 28, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 28, 2026

Choose a reason for hiding this comment

Uh oh!

mintlify Bot commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dprevoznik left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Sayan- left a comment

Choose a reason for hiding this comment

Uh oh!

Sayan- commented Jun 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ehfeng commented May 28, 2026 •

edited by cursor Bot

Loading

mintlify Bot commented May 28, 2026 •

edited

Loading

cursor Bot left a comment •

edited

Loading

cursor Bot left a comment •

edited

Loading

cursor Bot left a comment •

edited

Loading

cursor Bot left a comment •

edited

Loading

cursor Bot left a comment •

edited

Loading

cursor Bot left a comment •

edited

Loading