Skip to content

Split platform-induced API calls out of the control telemetry category - #322

Draft
archandatta wants to merge 1 commit into
mainfrom
archand/kernel-1870/telemetry-control-platform-split
Draft

Split platform-induced API calls out of the control telemetry category#322
archandatta wants to merge 1 commit into
mainfrom
archand/kernel-1870/telemetry-control-platform-split

Conversation

@archandatta

Copy link
Copy Markdown
Contributor

Summary

api_call telemetry was emitted for every documented operation and always landed in the control category. Most of that traffic is the platform acting on the VM, not the agent acting on the browser: recorder polling (listRecorders), profile save/restore (downloadDirZstd, deleteDirectory, processExec), replay lifecycle, and telemetry publishing itself. Anyone reading control to see what an agent did had to page past that noise, and the one event worth reading — executePlaywrightCode — didn't include the code that ran.

This splits the two apart:

  • Every operation in openapi.yaml now declares x-telemetry-category (control or platform). categorygen emits the operation → category map next to the existing event-type map, so a new endpoint without a classification fails generation instead of silently landing somewhere.
  • Browser-control operations (computer actions, executePlaywrightCode, screenshot, clipboard) keep emitting api_call under control. VM-management operations emit a new platform_api_call event under a new platform category.
  • platform is opt-in: it is in UserCategories but not DefaultCategories, so enabling telemetry without per-category settings now captures strictly less than before (control, connection, system, captcha, with control reduced to browser control).
  • BrowserApiCallEventData gains an optional code, recorded for executePlaywrightCode and clipped to 8 KB on a rune boundary (truncated set when clipped).
  • An operation the generated map doesn't know about falls back to platform, so an unclassified route can't dilute the stream callers read to see agent behavior.

Notes for review

  • The operation_id description said processExec/takeScreenshot, but the value on the wire is the generated handler name (ProcessExec). Corrected, and the generated map keys on that same form — categorygen rejects any operationId that isn't lowerCamelCase, since that assumption is what makes the mapping safe.
  • Classification calls worth a second look: takeScreenshot, readClipboard/writeClipboard are control (an agent uses them to see and to move data). patchDisplay, chromiumConfigure, patchChromiumFlags, uploadExtensionsAndRestart are platform (browser configuration, issued at session setup). processExec is platform even though a customer can call it directly — it isn't browser control.
  • The OTLP e2e test drove getTelemetry to generate control events; it now drives takeScreenshot, which is still control.

Follow-ups (not in this PR)

  • Control-plane exposure: the platform category needs to reach the browser-session telemetry config in the control plane (spec change ready) plus an SDK release before the dashboard can offer a platform filter chip. Until then platform events are produced but nothing enables them, so this PR alone just makes control clean.
  • CDP-level control events (clicks/typing issued over the CDP proxy) are still not emitted; the proxy has no per-command telemetry today.

Testing

make test-unit passes (go vet ./... + unit suite). e2e was not run here — it needs Docker.

Every documented operation emitted api_call under `control`, so the
platform's own traffic — recorder polling, profile save/restore, telemetry
publishing — buried the agent's browser actions.

Operations now carry `x-telemetry-category` in openapi.yaml and categorygen
emits the operation -> category map alongside the event-type map, so a new
endpoint without a classification fails generation. Browser-control calls
keep emitting api_call under `control`; VM-management calls emit
platform_api_call under a new `platform` category, which is opt-in and out
of the default set.

api_call data also gains an optional `code` field, recorded for
executePlaywrightCode and clipped to 8 KB on a rune boundary, so the event
says what actually ran.

Co-Authored-By: Claude Opus 5 <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant