Events

When events_enabled is on (the default), the limiter dispatches:

• RequestDeferred — string $key, int $delayMs, int $hitsInWindow, Timespan $timespan — right before a request is paused because the budget is exhausted (again, if the request loses the slot to another worker while it waits). The key, count and window describe the window that forced the wait (for a compound limit, the strictest one); hitsInWindow is the real number of requests recorded in it, 0 when an adaptive server penalty alone caused the wait.
• RequestAllowed — string $key, int $hitsInWindow, Timespan $timespan — after a request is recorded and allowed through, with the primary window’s hit count including this request.
• RateLimitReset — string $key — after ->reset() cleared a limit’s recorded hits (the primary limit’s key).

All three live in RoundlyConsulting\HttpClientRateLimits\Events. Listen for them to log, chart or alert on throttling:

use Illuminate\Support\Facades\Event;
use RoundlyConsulting\HttpClientRateLimits\Events\RequestDeferred;

Event::listen(function (RequestDeferred $event): void {
    logger()->warning('Throttled outbound request', [
        'key' => $event->key,
        'delay_ms' => $event->delayMs,
        'window' => $event->timespan->value,
    ]);
});

use Illuminate\Support\Facades\Event;
use RoundlyConsulting\HttpClientRateLimits\Events\RequestAllowed;

Event::listen(function (RequestAllowed $event): void {
    logger()->debug('Outbound request allowed', [
        'key' => $event->key,
        'hits' => $event->hitsInWindow,
        'window' => $event->timespan->label(), // 'Second' | 'Minute' | 'Hour' | 'Day'
    ]);
});

use Illuminate\Support\Facades\Event;
use RoundlyConsulting\HttpClientRateLimits\Events\RateLimitReset;

Event::listen(function (RateLimitReset $event): void {
    logger()->info('Rate limit reset', ['key' => $event->key]);
});

Turning events off

Set events_enabled to false for the lowest possible overhead:

HTTP_CLIENT_RATE_LIMITS_EVENTS_ENABLED=false