feat(transport): Add EnvelopePrinterTransport for debug logging

[ericapisani]

Adds EnvelopePrinterTransport, a decorator transport that wraps the real transport and pretty-prints each envelope's headers and item payloads to the SDK debug logger before forwarding the envelope.

Enabled via SENTRY_PRINT_ENVELOPES=1 (also accepts true/yes). When unset or falsy, no wrapping occurs and there's no runtime cost. Useful for local debugging without having to run a local Sentry instance or intercept network traffic.

Fixes PY-2398
Fixes #6183

[github-actions]

Codecov Results 📊

✅ 13 passed | Total: 13 | Pass Rate: 100% | Execution Time: 9.78s

📊 Comparison with Base Branch

Metric	Change
Total Tests	—
Passed Tests	—
Failed Tests	—
Skipped Tests	—

✨ No test changes detected

All tests are passing successfully.

❌ Patch coverage is 37.10%. Project has 15089 uncovered lines.
✅ Project coverage is 31.35%. Comparing base (base) to head (head).

Files with missing lines (1)

File	Patch %	Lines
transport.py	24.96%	⚠️ 442 Missing and 7 partials

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    31.35%    31.35%        —%
==========================================
  Files          190       190         —
  Lines        21930     21980       +50
  Branches      7382      7402       +20
==========================================
+ Hits          6876      6891       +15
- Misses       15054     15089       +35
- Partials       581       583        +2

---

Generated by Codecov Action

[linear-code]

PY-2398 Add transport for pretty-printing envelope contents when debugging span-first logic

[ericapisani]

bugbot run

[ericapisani]

@sentry review

[ericapisani]

bugbot run

[ericapisani]

@sentry review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

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

[alexander-alderman-webb]

The snippet below should probably work without crashing, since that's the canonical way to provide an alternative transport.

Maybe we create a transport which only prints to the terminal without wrapping another transport?

import sentry_sdk
from sentry_sdk.transport import _EnvelopePrinterTransport
sentry_sdk.init(
    dsn="...",
    transport=_EnvelopePrinterTransport,
)

[ericapisani]

@alexander-alderman-webb Given this transport is for debugging purposes on our end, I opted for the wrapping approach so that we don't need to change how we've configured the SDK, which was intended to include specific transports we may be leveraging for our use case.

Is there something in particular that you're concerned about with this approach?

[alexander-alderman-webb]

My main concern is that we need to set debug=True to see the envelopes with this approach (otherwise the logs are filtered out).
A smaller concern is that we will have to update the transport when we add new methods to the interface defined by the Transport base class. Ideally the new transport would be no maintenance effort at all 😄.

I agree that wrapping would be the nicest approach but I don't think our current abstractions were designed for this kind of wrapping 😞.

[cursor]

Silent exception swallowing hides debug tool failures

Low Severity

The bare except Exception: pass in capture_envelope silently swallows all errors during envelope printing without any feedback. Since this is specifically a debugging tool activated by SENTRY_PRINT_ENVELOPES=1, silently failing defeats the tool's purpose — a developer who enables it and sees no output would have no way to know why. The SDK's own capture_internal_exceptions pattern logs exceptions rather than discarding them entirely.

 

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

[cursor]

Envelope printing uses debug level, invisible without debug=True

Medium Severity

All logging in _EnvelopePrinterTransport.capture_envelope uses logger.debug(), but the SDK's _DebugFilter (in debug.py) suppresses all log messages when debug=True is not set in the SDK options. This means SENTRY_PRINT_ENVELOPES=1 alone won't produce any output — users must also configure debug=True, which contradicts the PR description stating the feature is "Enabled via SENTRY_PRINT_ENVELOPES=1." The reviewer explicitly discussed this and suggested using logger.info instead, but the change hasn't been applied to any of the logging calls.

 

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

[alexander-alderman-webb]

Suggested change

	def __init__(self, transport: "Transport") -> None:
	Transport.__init__(self, options=transport.options)
	self._inner = transport
	self.parsed_dsn = transport.parsed_dsn
	def __init__(self, transport: "Transport") -> None:
	Transport.__init__(self, options=transport.options)
	self._inner = transport
	self.parsed_dsn = transport.parsed_dsn
	self.envelope_logger = logging.getLogger("sentry_sdk.envelopes")
	self.envelope_logger.setLevel(logging.DEBUG)

[sentry]

Bug: When SENTRY_PRINT_ENVELOPES=1 is set without a DSN, make_transport returns a truthy object instead of None, causing unintended side effects like spawning a background thread.
_{Severity: MEDIUM}

Suggested Fix

In make_transport, the _EnvelopePrinterTransport should only wrap the transport object if it is not None. This ensures that when no DSN is configured and no other transport is available, make_transport correctly returns None, preventing the creation of unnecessary resources.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: sentry_sdk/transport.py#L1255-L1258

Potential issue: When the `SENTRY_PRINT_ENVELOPES=1` environment variable is set without
a DSN configured, the `make_transport` function incorrectly returns a truthy
`_EnvelopePrinterTransport(None)` object instead of `None`. This causes the `Client` to
behave as if a valid transport exists, leading to several unintended side effects. A
backpressure `Monitor` is created, which in turn spawns a background daemon thread that
runs unnecessarily. It also triggers a superfluous call to
`check_uwsgi_thread_support()`. Furthermore, `capture_event` will return a non-`None`
event ID, giving the false impression that an event was sent when it was actually
dropped.

[cursor]

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

There are 3 total unresolved issues (including 2 from previous reviews).

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

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

[cursor]

Wrapping None transport changes make_transport return behavior

Medium Severity

When SENTRY_PRINT_ENVELOPES is set but no DSN is configured, make_transport now returns a non-None _EnvelopePrinterTransport(None) instead of None. Code in client.py that checks if self.transport: (e.g., to set up Monitor, call record_lost_event, check parsed_dsn) now takes branches that were previously skipped without a DSN. The wrapping of transport here likely needs a guard to only wrap when transport is not None.

 

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