[Claimed #2738] fix(protocol): make telemetry export opt-in

Merged
GI
2mo ago
+120-72

Mirrored from external contributor PR #2738 after approval by @miguelg719.

Original author: @abhinavkr26104
Original PR: https://github.com/browserbase/stagehand/pull/2738
Approved source head SHA: e77c269fcc7ab33d2b76f213f26da62b77b1e826

@abhinavkr26104, please continue any follow-up discussion on this mirrored PR. When the external PR gets new commits, this same internal PR will be marked stale until the latest external commit is approved and refreshed here.

Original description

why

The v4 init schema supplied https://example.com/v1/traces whenever callers omitted telemetry. The extension treated that placeholder as an intentional OTLP destination, creating guaranteed-failing background exports and possible shutdown delays for otherwise default Stagehand instances.

Fixes #2732

what changed

  • Make stagehand.init telemetry optional instead of injecting a placeholder endpoint.
  • Leave extension tracing inert when no telemetry configuration is supplied while preserving explicit OTLP export behavior.
  • Regenerate Python and Go protocol models and the embedded Go extension bundle.
  • Keep Go's existing value-style public telemetry option while omitting its zero value from the wire.
  • Document that telemetry export is disabled by default and add protocol/runtime/SDK regression coverage.
  • Add patch Changesets for the extension and SDKs.

test plan

  • Protocol unit suite: 26 files passed, 359 tests passed.
  • Extension unit suite: 45 files passed, 334 tests passed, 10 existing TODOs.
  • Focused TypeScript SDK create tests passed, including omitted and explicit telemetry.
  • Python focused tests: 200 passed, 1 skipped; generated-model freshness, Ruff format, and Ruff lint checks passed.
  • Full Python suite attempted: 455 passed, 2 skipped; only the two pre-existing Windows path assertions tracked by #2733 failed.
  • Go SDK suite excluding the intentionally separate examples package passed.
  • Protocol type-check and extension production build passed.
  • Targeted Oxfmt, Oxlint, Changesets validation, and git diff --check passed.
  • The full JavaScript unit run was attempted; unrelated Windows/environment failures remain in SDK path assertions, package-manager spawning, and file metadata handling.

Summary by cubic

Makes telemetry export opt-in so omitted telemetry no longer injects a placeholder endpoint that caused guaranteed-failing exports and shutdown delays. stagehand.init no longer defaults to https://example.com/v1/traces; omitting telemetry leaves tracing inert, while explicit telemetry keeps OTLP export.

  • Protocol: stagehand.init.telemetry is now optional with no default; schema, integrity, and wire-casing tests updated.
  • Extension: createStagehandTracing.configure accepts undefined and skips runtime creation; flush/shutdown become no-ops when telemetry is absent.
  • SDKs: TypeScript omits telemetry from the wire when unset; Go's StagehandInitParams.Telemetry is now *TelemetryConfig and omits the zero value via optionalTelemetry, while CreateOptions.Telemetry stays value-style; Python marks telemetry as Optional with the placeholder default removed.
  • Release: Patch changesets added for the five affected packages.

Migration

  • No action needed; placeholder export errors and shutdown delays disappear.
  • Set telemetry.traces.endpoint to an OTLP collector (ending in /v1/traces) with required headers to enable export.
  • Go: pass nil to omit telemetry or set a non-empty endpoint/headers to enable; direct StagehandInitParams construction now requires *TelemetryConfig.