feat: Make transport channel capacity configurable

[mvanhorn]

Summary

Adds a transport_channel_capacity field to ClientOptions so users can tune the bounded channel size used by the transport thread. The default remains 30, preserving existing behavior.

Why this matters

In high-throughput scenarios (many transactions with single spans each), the hardcoded capacity of 30 can saturate quickly, leading to dropped envelopes. This was identified in #923 and tracked in #994. Making it configurable lets users trade memory for reliability based on their workload.

Changes

• sentry-core/src/clientoptions.rs: Added transport_channel_capacity: usize field (default: 30)
• sentry/src/transports/thread.rs: Accept channel_capacity parameter in TransportThread::new
• sentry/src/transports/tokio_thread.rs: Same change for the async transport variant
• sentry/src/transports/curl.rs: Pass options.transport_channel_capacity to TransportThread::new
• sentry/src/transports/reqwest.rs: Same
• sentry/src/transports/ureq.rs: Same

Testing

• cargo check passes across the full workspace
• Default behavior unchanged (capacity stays at 30 unless explicitly configured)
• Approach matches the one proposed in feat: Make transport channel capacity configurable #923

Closes #994

This contribution was developed with AI assistance (Claude Code).

[codecov]

Codecov Report

❌ Patch coverage is 3.70370% with 156 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.69%. Comparing base (a57b91c) to head (6f724ba).
⚠️ Report is 51 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1040      +/-   ##
==========================================
- Coverage   73.81%   73.69%   -0.12%     
==========================================
  Files          64       65       +1     
  Lines        7538     7577      +39     
==========================================
+ Hits         5564     5584      +20     
- Misses       1974     1993      +19     

[szokeasaurusrex]

Hi @mvanhorn, thanks for the contribution! Before I proceed to a full review, please address the CI failures and the AI review agent comments. If any of the AI review comments are inaccurate, please comment on them and mark as resolved. Thanks!

[mvanhorn]

Addressed in 9c8f904:

• Added transport_channel_capacity to the manual Debug impl
• Clamped capacity to min 1 to prevent rendezvous channel (try_send would silently drop)
• Ran cargo fmt

[szokeasaurusrex]

Thanks again for the contribution. I think we should revise the public API shape to avoid public API breakages before merging this change.

The current implementation introduces public API breakage by:

• adding a new public field to ClientOptions
• changing the signatures of the public transport thread constructors

I would like to avoid those breakages here and instead expose this as additive API:

• add additive with_capacity(...) constructors on the public transport thread types, i.e. StdTransportThread::with_capacity(send, channel_capacity) and TokioTransportThread::with_capacity(send, channel_capacity)
• keep the existing new(...) signatures unchanged, but make those constructors delegate to with_capacity(..., 30)
• add transport-specific constructors such as ReqwestHttpTransport::with_channel_capacity(options, channel_capacity) (and similarly for curl and ureq), which would use those new with_capacity(...) thread constructors internally
• document use through ClientOptions.transport

That still gives users a way to override the transport queue capacity via the existing TransportFactory mechanism, without changing ClientOptions yet.

For example, initializing the SDK with a custom capacity could look like this:

let opts = ClientOptions {
    transport: Some(Arc::new(move |opts| {
        Arc::new(ReqwestHttpTransport::with_channel_capacity(opts, 256))
    })),
    ..Default::default()
};

If you are open to it, please refactor the PR in that direction. If not, let me know and I can take it over as a follow-up.

[mvanhorn]

Thanks for the direction @szokeasaurusrex. Refactored to the additive shape you described in fbff3ea:

• TransportThread::new(send) restored to the original signature. New TransportThread::with_capacity(send, channel_capacity) is the entry point for custom capacity (clamped to a minimum of 1 to avoid the rendezvous channel). Same pattern in tokio_thread::TransportThread.
• ReqwestHttpTransport::with_channel_capacity(options, channel_capacity) added. new(options) / with_client(options, client) keep the default capacity of 30. Same for CurlHttpTransport and UreqHttpTransport (with_agent likewise unchanged).
• Removed transport_channel_capacity from ClientOptions (field, Default, and the manual Debug impl).

Your example works unchanged:

let opts = ClientOptions {
    transport: Some(Arc::new(move |opts| {
        Arc::new(ReqwestHttpTransport::with_channel_capacity(opts, 256))
    })),
    ..Default::default()
};

cargo check --workspace --all-features, cargo fmt --all, and cargo clippy --workspace --all-features all pass.

[sentry]

Bug: The transport_channel_capacity field is missing from ClientOptions. Transports default to a hardcoded capacity of 30, ignoring any user-provided value on the options struct.
_{Severity: HIGH}

Suggested Fix

Add the transport_channel_capacity: Option<usize> field to the ClientOptions struct. In the DefaultTransportFactory and other transport creation logic, read this value from the options and pass it to the transport's internal constructor, falling back to the default of 30 if it's not set. This will align the implementation with the documented feature.

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/src/transports/curl.rs#L23-L26

Potential issue: The feature to configure transport channel capacity via `ClientOptions`
is not implemented as described. The `transport_channel_capacity` field is missing from
the `ClientOptions` struct. As a result, the default transport factory and individual
transport constructors (`CurlHttpTransport`, `ReqwestHttpTransport`,
`UreqHttpTransport`) all use a hardcoded channel capacity of 30. Users attempting to set
this value on `ClientOptions` will find it has no effect. The only way to set a custom
capacity is to manually construct a transport using the new `with_channel_capacity()`
methods, which bypasses the standard client initialization path. This is problematic for
high-throughput use cases where a larger capacity is needed to prevent event drops.

[cursor]

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

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

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

[cursor]

Transport capacity not read from ClientOptions, feature non-functional

High Severity

The new() methods in all three transports hardcode 30 instead of reading from options. Additionally, transport_channel_capacity was never actually added to ClientOptions (the field does not exist). The DefaultTransportFactory::create_transport calls HttpTransport::new(options), which passes the hardcoded 30 to new_internal. This makes the entire feature non-functional — users have no way to configure the channel capacity through the standard ClientOptions API as the PR intends.

Additional Locations (2)

• sentry/src/transports/curl.rs#L19-L21
• sentry/src/transports/ureq.rs#L21-L23

 

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