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: 7.39s

📊 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 46.00%. Project has 15077 uncovered lines.
✅ Project coverage is 31.37%. Comparing base (base) to head (head).

Files with missing lines (1)

File	Patch %	Lines
transport.py	25.48%	⚠️ 430 Missing and 7 partials

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    31.35%    31.37%    +0.02%
==========================================
  Files          190       190         —
  Lines        21930     21968       +38
  Branches      7382      7386        +4
==========================================
+ Hits          6876      6891       +15
- Misses       15054     15077       +23
- 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)

[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.}