feat(telemetry): opt-out, isolated Sentry error telemetry for the SDK - #756
Open
GregHolmes wants to merge 4 commits into
Open
feat(telemetry): opt-out, isolated Sentry error telemetry for the SDK#756GregHolmes wants to merge 4 commits into
GregHolmes wants to merge 4 commits into
Conversation
Add a hand-written SDK observability module that builds an isolated Sentry client (never the global sentry_sdk.init()) wired into client.py via the telemetry_opt_out / telemetry_handler constructor params. Adds the optional sentry-sdk dependency and a 'telemetry' extra, freezes the module and its test in .fernignore, and adds a regression test.
- Route capture through a per-client TelemetrySink instead of module globals, so one client's opt-out or handler no longer leaks to another (fixes the opt-out bypass and sticky-handler bugs) - Stop hardcoding environment="production"; honour DEEPGRAM_TELEMETRY_ENVIRONMENT, otherwise leave it unset - Make install_response_capture genuinely idempotent (guard against stacking duplicate response hooks) - Correct the DeepgramClient telemetry_opt_out/telemetry_handler docstrings, which still described the params as no-ops - Redact the home-dir username from stack-frame abs_path/filename in scrub_event - Update and extend the telemetry tests
GregHolmes
requested review from
deepgram-kiley and
dg-coreylweathers
as code owners
August 11, 2026 09:01
… in scrub CI runs mypy without the optional telemetry extra installed, so the TYPE_CHECKING import of sentry_sdk.types failed with import-not-found. Add the same # type: ignore[import-not-found] already used on the other sentry imports in client.py.
paultill
requested changes
Aug 12, 2026
paultill
left a comment
paultill
left a comment
There was a problem hiding this comment.
Sounds good. I'll state what I am hoping for concisely:
- For the first version, be as minimal as possible to keep complexity low. (Add more later once we de-risk the initial deployment of telemetry)
- Either modify Luke's doc or write your own doc to describe the PR's design. It should focus more on what you value rather than repeating the technical details that appear in the PR. Shorter is better!
- Be intentional about how you know that the new functionality in the SDK doesn't break client applications. This should be both testing (CC @Edward Rosen) and some design considerations such as bounded resource usage and making sure that errors posting telemetry are contained.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds an opt-out, isolated, error-only Sentry telemetry module (
src/deepgram/telemetry/), wired intoDeepgramClient/AsyncDeepgramClientvia the existingtelemetry_opt_outandtelemetry_handlerparams. The goal is visibility into SDK failures (HTTP 5xx, transport/SDK errors) without touching customer data or the host app's own Sentry.Design
sentry_sdk.init(); builds a privateClientwithdefault_integrations=False, so we only ever capture SDK-originated errors and leave the customer's own Sentry setup untouched. This follows Sentry's own guidance for library authors.TelemetrySink, so one client's opt-out or custom handler can't leak into another's.send_default_pii=False,include_local_variables=False,max_request_body_size="never", plus abefore_sendscrubber that strips request bodies, query strings, cookies, credential headers,server_name,user(incl. geo), and redacts the home-dir username from stack-frame paths (/Users/<name>/...->/Users/<redacted>/...).Safety / posture
telemetry_opt_outdefaults toTrue,_EMBEDDED_DSNis empty, and aDEEPGRAM_TELEMETRY_DISABLEDkill-switch wins over everything. With no resolvable DSN this no-ops entirely, so merging this ships nothing live — arming is a separate, gated step.sentry-sdk's background worker (network post is off the request path).Testing
tests/custom/test_telemetry.pycovers opt-out resolution, the env kill-switch, PII/secret scrubbing, stack-frame path redaction, per-client isolation, and host-app isolation.pytest,ruff, andmypyall pass.