fix(protocol): make telemetry export opt-in

Closed
AB
2mo ago
+121-74

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. Previously, stagehand.init defaulted to https://example.com/v1/traces; now, omitting telemetry leaves tracing inert and explicit telemetry keeps OTLP export.

  • Protocol: stagehand.init.telemetry is optional; defaults removed; schema and integrity/wire-casing tests updated.
  • Extension: createStagehandTracing.configure accepts undefined and skips runtime; flush/shutdown are no-ops when telemetry is absent; tests cover this.
  • SDKs: TS omits telemetry from the wire when unset; Go generates *TelemetryConfig and sends partial configs (e.g., headers-only) while omitting the zero value; Python's telemetry is optional with the default removed.
  • Docs: Observability notes telemetry export is disabled by default.
  • Release: Patch changesets for @browserbasehq/stagehand, @browserbasehq/stagehand-go, @browserbasehq/stagehand-python, and @browserbasehq/stagehand-extension.

Migration

  • No action needed for defaults; placeholder export errors and shutdown delays stop.
  • To enable telemetry, set telemetry.traces.endpoint to your OTLP collector (must end with /v1/traces) and include required headers.
  • Go: Pass nil to omit telemetry or set a non-empty Telemetry.Traces.Endpoint (or headers) to enable export; value-style options are unchanged.