fix(protocol): make telemetry export opt-in
Closed
AB
2mo ago+121+121+012345678901234567890123456789-74-74-01234567890123456789
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.inittelemetry 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 --checkpassed. - 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.telemetryis optional; defaults removed; schema and integrity/wire-casing tests updated. - Extension:
createStagehandTracing.configureacceptsundefinedand skips runtime; flush/shutdown are no-ops when telemetry is absent; tests cover this. - SDKs: TS omits
telemetryfrom the wire when unset; Go generates*TelemetryConfigand sends partial configs (e.g., headers-only) while omitting the zero value; Python'stelemetryis 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.endpointto your OTLP collector (must end with/v1/traces) and include required headers. - Go: Pass
nilto omit telemetry or set a non-emptyTelemetry.Traces.Endpoint(or headers) to enable export; value-style options are unchanged.