diff --git a/browsers/telemetry/categories.mdx b/browsers/telemetry/categories.mdx index e209af2..cb7288b 100644 --- a/browsers/telemetry/categories.mdx +++ b/browsers/telemetry/categories.mdx @@ -13,11 +13,67 @@ 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` | +| `control` | Actions that drive the browser: computer-control calls, Playwright code execution, screenshots and clipboard access, plus browser-control commands sent over the CDP proxy | `api_call`, `cdp_command` | +| `platform` | Calls that manage the VM rather than drive the browser: recording lifecycle, filesystem, process execution, log streaming, scale-to-zero, telemetry and browser configuration | `platform_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` | +`control` answers "what did my agent do." `platform` is mostly Kernel acting on the VM on your behalf - saving a profile, capturing a replay, polling a recorder - so it is off by default even though the rest of this group is on. Enable it when you are debugging a profile save, a replay, or a session-setup step rather than the agent itself. + + +`control` reports one `cdp_command` for each supported browser-control command it can classify from the CDP proxy - input gestures, navigation, dialogs, file selection, screenshots, and every command phase, including `mouseMoved`, `keyUp`, and `char`. It doesn't report arbitrary CDP traffic; general inspection traffic such as most DOM and Runtime commands isn't classified as browser control. The command stream isn't sampled, coalesced, or reordered. + + +### Reduce CDP command volume + +Use `control.cdp.excluded_methods` to omit high-volume methods such as `Input.dispatchMouseEvent` during a humanized cursor path or `Page.captureScreenshot` during a screencast: + + +```typescript Typescript/Javascript +import Kernel from '@onkernel/sdk'; + +const kernel = new Kernel(); + +const browser = await kernel.browsers.create({ + telemetry: { + browser: { + control: { + enabled: true, + cdp: { + excluded_methods: ['Input.dispatchMouseEvent', 'Page.captureScreenshot'], + }, + }, + }, + }, +}); +``` + +```python Python +from kernel import Kernel + +kernel = Kernel() + +browser = kernel.browsers.create( + telemetry={ + "browser": { + "control": { + "enabled": True, + "cdp": { + "excluded_methods": [ + "Input.dispatchMouseEvent", + "Page.captureScreenshot", + ], + }, + }, + }, + }, +) +``` + + +Exclusion affects telemetry only; the commands still reach the browser. On `cdp_disconnect`, `telemetry_excluded` counts configured exclusions, while `telemetry_dropped` counts supported commands that reached the browser but whose telemetry events weren't emitted. + ## 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 highly granular page-level events. Capturing them adds overhead, so enable only the ones you need. @@ -25,8 +81,8 @@ These categories report what's happening in the page. Capturing any of them atta | 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` | +| `network` | Network requests, responses, and failures | `network_request`, `network_response`, `network_loading_failed`, `network_idle`, `proxy_error` | +| `page` | Navigation and page lifecycle, including performance signals and renderer crashes | `page_navigation`, `page_dom_content_loaded`, `page_load`, `page_tab_opened`, `page_crashed`, `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` | @@ -42,7 +98,7 @@ It isn't directly settable. It flows automatically whenever any of the browser-a ## Data sensitivity -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. +Telemetry is off by default. The default set avoids page content, but `control` records the source you submit for Playwright execution and sanitized arguments for supported browser-control commands. The browser-activity categories capture what flows through the page, which is your own browser's data and can include credentials and personal information. | Category | Can contain sensitive data | | --- | --- | @@ -51,14 +107,17 @@ Telemetry is off by default and the default set carries operational metadata onl | `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. | +| `control` | The source you submit to the Playwright code-execution endpoint, on the `code` field of `api_call`, capped at 8 KB and marked with `...[truncated]` when cut. Whatever your script embeds is captured with it, so a literal password or token in the snippet is captured too. `cdp_command` carries sanitized arguments such as the method and phase, coordinates, counts, flags, and named keys such as `Enter` and `Tab`. Typed text, file paths, scripts, templates, dialog input, and autofill values aren't captured; navigation commands retain only the URL scheme, not the host, path, query, or fragment. | +| `platform`, `connection`, `system`, `captcha`, `monitor` | Session metadata only (VM-management calls, connection and health events). No page 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. Events are retained for 30 days, then expired (see [Retention](/browsers/telemetry/overview#retention)). 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. +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), and `cdp_command` reports text lengths rather than the text itself. 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 capture `control` and run Playwright code, pass credentials in through variables your snippet reads rather than as literals in the submitted source, so the captured `code` doesn't carry them. -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 your organization has a BAA with Kernel, the `network`, `console`, and `screenshot` categories are disabled and can't be captured. +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 your organization has a BAA with Kernel, the `network`, `console`, and `screenshot` categories are disabled and can't be captured. `control` stays available; keep regulated values out of the Playwright source you submit, since that source is captured. If you have compliance requirements around what Kernel may process, [contact us](mailto:security@kernel.sh) before enabling them.