Download the PHP package webparking/laravel-sentry-throttling without Composer

Throttle exceptions being sent to Sentry

Laravel has a built-in mechanism for throttling exceptions, but it can't define throttling rules per reportable. This package throttles exceptions specifically before they are sent to Sentry, so you can keep logging everything locally while avoiding repeated reports of the same exception in Sentry.

Compared to Sentry's own percentage-based sample_rate, this is exception-specific. On top of that, every event that survives a throttle, whether rate-limited or sampled, is tagged so you don't lose sight of how noisy it really was:

• throttled = true: the event passed through a throttle.
• throttle_occurrences = <count>: how many matching exceptions occurred (dropped and sent) since the previous event of this kind was reported.

Because those tags are indexed by Sentry, you can search and alert on them (e.g. throttled:true, or sort by throttle_occurrences).

Installation

Install via composer:

The package registers itself as sentry.before_send automatically, but only if your project hasn't already configured one, so it never silently clobbers an existing callback. You do not need to touch config/sentry.php unless one of the cases below applies.

If you already have a before_send

Auto-registration backs off when sentry.before_send is already set. Call the throttle from within your own callback to keep both behaviors:

Registering it explicitly

If you prefer to be explicit rather than rely on auto-registration:

Usage

Implement the ThrottlesSentryReports interface in a class of your own. For each exception it returns a Limit (rate-limit), a Lottery (probabilistic sample), or null to let the exception through untouched (Limit::none() does the same). Both a rate-limited survivor and a sampled survivor are tagged with throttled and throttle_occurrences.

Then bind it in the container, typically in App\Providers\AppServiceProvider::register():

The class can live anywhere and be named anything. The package only cares that something is bound to ThrottlesSentryReports. If you're on Laravel 10 or earlier and prefer to co-locate the logic with your existing App\Exceptions\Handler, implement the interface there and bind ThrottlesSentryReports::class to it instead. If nothing is bound, the throttle stays out of the way and every event is sent as usual.

How the throttle bucket is keyed

Each exception is counted and throttled against a bucket. For a Limit, the bucket is whatever you pass to Limit::by(); without it, the bucket defaults to the exception's class, so all instances share one bucket. A Lottery has no key, so it always buckets by exception class.

Migrating from esign/laravel-sentry-throttling

This package is a behavioral superset of esign/laravel-sentry-throttling: the ThrottlesSentryReports interface and its throttleSentry() signature are identical, so your existing throttling rules keep working. On top of that you get the throttled / throttle_occurrences tags and automatic before_send registration.

Migration is a find/replace:

1. Swap the dependency:

2. Replace Esign\SentryThrottling with Webparking\SentryThrottling throughout your code (the interface import, the before_send reference, the provider).
3. Optionally drop your manual before_send line from config/sentry.php, since the package now registers it for you when it isn't already set.

Supported versions

Every combination below is exercised in CI:

Testing & local development

The full PHP × Laravel matrix runs locally via act, executing the exact CI workflow in Docker:

For day-to-day work there's a Docker workspace pinned to the newest supported combination (PHP 8.5 / Laravel 13):

Prefer running things yourself? composer install && composer test works too.

Thanks

This package is heavily inspired by, and builds directly on the ideas of, esign/laravel-sentry-throttling by Esign. The ThrottlesSentryReports interface, the before_send throttling approach, and the test setup all originate from their excellent work. Thank you. 🙏

License

The MIT License (MIT). Please see the License File for more information.