fix(client): release the global OTel tracer provider on shutdown

[XieX]

Companion to launchdarkly/js-ai-sdk#103, which fixes the same lifecycle bugs in JS. Two of them exist here, and one has a Python-specific counterpart.

1. An init/shutdown/init cycle exported nothing

shutdown() dropped its provider handle but left OpenTelemetry's global tracer provider registered. That global is once-guarded — a second set_tracer_provider logs Overriding of current TracerProvider is not allowed and keeps the provider already in place — so after a re-init, every span routed to the provider that had just been shut down. Observed across two cycles: the global service.name stayed cycle1 and now correctly becomes cycle2.

Releasing it means resetting both the global slot and the Once that guards it; clearing the slot alone leaves the guard tripped, so the next set is a silent no-op. Both are private, since opentelemetry-python has no public way to unset them, so _release_otel_globals's docstring explains the reach. The propagator needs no reset — set_global_textmap is a plain assignment.

The release only happens when our set_tracer_provider actually took effect (trace.get_tracer_provider() is provider). Bugbot caught that the first version gated it on having built a provider, which would have wiped a host app's already-registered provider; the JS PR had the same flaw. A refused set now logs a warning.

2. A failed telemetry setup left a half-initialized client behind

_client is not None is the idempotency guard, but _client was assigned before _setup_telemetry ran. A malformed OTEL_EXPORTER_OTLP_TIMEOUT makes setup raise, and _client stayed set: the next init_client() returned the client as a silent success with no telemetry, and on the SDK-key path its connection was never closed. _client is now assigned only after setup succeeds. On the SDK-key path the client we built is closed on failure; a BYOC client is left open, since the caller owns it. JS's counterpart was a cached failed-init promise.

Not a bug here: BYOC idempotency

JS checked the singleton below the pre-initialized-client branch and re-registered OTel on every initClient(client). _resolve_client checks it first — 1 _setup_telemetry call across three inits — and two tests pin that ordering.

Verification

• 8 new tests; each one covering a bug here was confirmed to fail against the code it fixes. The end-to-end cycle and env-var tests drive the real _setup_telemetry, with the OTLP exporter stubbed or failing before any network use.
• Full suite 1356 pass. ruff check, ruff format, and mypy are clean.

🤖 Generated with Claude Code

---

Note

Overview
Fixes Python client lifecycle bugs aligned with the JS SDK: init/shutdown/init no longer leaves spans routed to a shut-down tracer provider, and failed telemetry setup no longer leaves a half-initialized singleton client.

shutdown() now clears OpenTelemetry’s once-guarded global tracer registration (via _release_otel_globals) only when this SDK’s set_tracer_provider actually won (_owns_otel_globals). If another library registered first, setup logs a warning and shutdown does not tear down the host app’s provider. Test reset mirrors the same release so multi-init suites do not leak globals.

init_client assigns _client only after _setup_telemetry succeeds. On the SDK-key path, a telemetry failure closes the newly created LD client; BYOC clients are left open for the caller. Repeat inits still run telemetry setup at most once (idempotency check first).

Docs in agents.md describe the shutdown/release behavior; test_lifecycle.py adds coverage for cycles, foreign providers, failed setup, and idempotency.

^{Reviewed by Cursor Bugbot for commit ebb6c1e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d5ee277. Configure here.}