[Claimed #2738] fix(protocol): make telemetry export opt-in
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.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. 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.telemetryis now optional with no default; schema, integrity, and wire-casing tests updated. - Extension:
createStagehandTracing.configureacceptsundefinedand skips runtime creation; flush/shutdown become no-ops when telemetry is absent. - SDKs: TypeScript omits
telemetryfrom the wire when unset; Go'sStagehandInitParams.Telemetryis now*TelemetryConfigand omits the zero value viaoptionalTelemetry, whileCreateOptions.Telemetrystays value-style; Python markstelemetryasOptionalwith 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.endpointto an OTLP collector (ending in/v1/traces) with required headers to enable export. - Go: pass
nilto omit telemetry or set a non-empty endpoint/headers to enable; directStagehandInitParamsconstruction now requires*TelemetryConfig.