Download the PHP package nikolaynesov/laravel-serene without Composer

Laravel Serene

Graceful, noise-free, and rate-limited exception reporting for Laravel. Stop spamming your error tracking service with duplicate errors and get meaningful insights into how many times errors occurred and how many users were affected.

Features

• Rate Limiting: Automatically throttles duplicate errors to prevent spam
• Affected User Tracking: Tracks all users affected by an error during the cooldown period
• Intelligent Error Grouping: Interface-based grouping for exceptions with dynamic messages
• Metrics & Stats: Provides occurrence and throttle statistics for each error
• Memory Protection: Configurable caps prevent cache overflow in catastrophic scenarios
• Provider Agnostic: Works with Bugsnag, Sentry, or any custom error reporter
• Cache Driver Compatible: Works with any Laravel cache driver (Redis, Memcached, File, etc.)
• Easy Integration: Simple facade interface and automatic Laravel discovery

Installation

Install the package via Composer:

The package will automatically register itself via Laravel's package discovery.

Publish Configuration

Publish the configuration file:

This will create a config/serene.php file.

Environment Variables

Add these to your .env file to configure Serene:

All environment variables are optional. If not set, the defaults shown above will be used.

Using with Bugsnag

If you're using Bugsnag, install the Bugsnag Laravel package:

Then configure Bugsnag according to their documentation.

Set the provider in config/serene.php:

Using with Laravel Logs

To simply log errors to your Laravel logs:

Usage

Integration with Laravel Exception Handler

The recommended way to use Serene is to integrate it with Laravel's exception handler. This automatically reports all exceptions with user context:

This will automatically report all exceptions with the current user's ID, enabling proper user tracking and Bugsnag identification.

Basic Usage

You can also use the Serene facade directly in your code:

Tracking Affected Users

Track which users are affected by an error:

When the error is reported, the context will include:

• affected_users: Array of user IDs affected during the cooldown period (up to max_tracked_users)
• affected_user_count: Total number of affected users tracked
• user_tracking_capped: Boolean indicating if the user tracking limit was reached

Important: If using Bugsnag, the first affected user will be set as the primary user for the error report, enabling proper user filtering and search in Bugsnag's Users tab. All affected users remain visible in the metadata.

Enhanced Bugsnag Integration

When using BugsnagReporter, you can provide additional context fields that will enrich the Bugsnag error report:

Recognized fields for Bugsnag:

• user_email - Sets email on Bugsnag user (visible in Users tab)
• user_name - Sets name on Bugsnag user
• severity - Sets error severity (error, warning, info)
• app_version - Adds application version to metadata

All fields remain in the error_throttler metadata tab for reference.

Adding Custom Context

Add any additional context to help with debugging:

Error Grouping

Serene provides three ways to control how errors are grouped, from most flexible to automatic. The resolved group key does two things:

1. Throttling — occurrences sharing a key collapse into a single cooldown window.
2. Tracker grouping — the key drives the error tracker's native grouping, so all occurrences of a group appear as one error regardless of stacktrace.

Tracker grouping is controlled by the group_by_key config (default true). Set it to false to keep the tracker's default stacktrace-based grouping and have the key affect throttling only. See Tracker Grouping below.

1. Groupable Exceptions (Recommended)

Implement the GroupableException interface on your custom exceptions to define automatic error grouping:

Benefits:

• Solves the dynamic message problem automatically
• No need to specify keys at call sites
• Self-documenting exceptions
• Works across your entire codebase

Example with dynamic grouping:

2. Explicit Custom Keys

Override grouping with an explicit key parameter for one-off cases:

When to use: Third-party exceptions you can't modify, or temporary overrides.

3. Auto-Generated Keys

If no interface or explicit key is provided, errors are grouped by exception class + message hash:

Hierarchy: Explicit key > GroupableException > Auto-generated

Tracker Grouping

By default the resolved group key drives the error tracker's native grouping, so getErrorGroup() and explicit keys control how errors group in your tracker's dashboard, not just Serene's throttling — all occurrences of a group collapse into a single error, even when their stacktraces differ.

Each reporter applies this in its own way: the bundled BugsnagReporter sets Bugsnag's grouping hash; a custom reporter for another tracker would map the key to that tracker's equivalent (e.g. Sentry's fingerprint), and a reporter without native grouping simply ignores the flag. The resolved key is always available to every reporter as $context['key'].

This is enabled by default. To opt out and keep the tracker's default stacktrace-based grouping:

Upgrading from < 0.3.0: Earlier versions never applied the key to tracker grouping, so errors grouped by stacktrace. After upgrading, errors reported through Serene will re-group by their key: existing stacktrace-based errors stop receiving events and new key-based errors appear. You may want to mark the superseded errors as fixed. Set group_by_key => false to preserve the old behavior.

How It Works

Rate Limiting Logic

1. First Occurrence: When an error occurs for the first time, it's immediately reported to your error tracking service
2. Cooldown Period: A cooldown timer starts (default: 30 minutes)
3. Subsequent Occurrences: If the same error occurs again during the cooldown:
   • It's not reported (preventing spam)
   • User IDs are collected if provided (up to max_tracked_users limit)
   • Occurrence and throttle counters are incremented
4. After Cooldown: When the cooldown expires, the next occurrence will be reported with full statistics

Reported Context

When an error is reported, the following context is automatically added:

Debug Logging

Enable debug logging to monitor throttling behavior:

Or in config:

When enabled, Serene logs all activity:

Note: Keep debug logging disabled in production to avoid log clutter. Only enable when investigating throttling issues.

Creating Custom Providers

Simple Custom Provider

You can create your own error reporter by implementing the ErrorReporter interface:

Then configure it in config/serene.php:

Advanced Bugsnag Customization

For advanced Bugsnag integration beyond the built-in fields, extend the BugsnagReporter. Configure your custom reporter:

This approach gives you complete control over the Bugsnag integration while maintaining Serene's rate limiting and user tracking features.

Advanced Configuration

Adjusting Cooldown Period

Change the cooldown period based on your needs:

Per-Environment Configuration

Configure different settings per environment using .env files:

Or dynamically in config config/serene.php

Cache Memory Management

Serene provides two-level protection against cache memory issues:

1. Per-Error User Tracking Cap (max_tracked_users)

Limits the number of users tracked per individual error (default: 1000).

Memory calculation per error:

• 1000 users × 8 bytes = ~8KB per error

When user_tracking_capped is true in the error context, it indicates a widespread issue affecting many users.

Adjust for high-traffic applications:

2. Global Error Tracking Cap (max_tracked_errors)

Limits the total number of unique errors tracked simultaneously (default: 1000).

Total memory calculation:

• 1000 unique errors × 8KB = ~8MB total (worst case with max users per error)
• Safe for any Redis instance with 512MB+ RAM

How it works:

• Tracks up to 1000 unique errors with full throttling enabled
• When limit is reached, new errors are reported immediately without throttling (fail-open)
• Expired errors are automatically cleaned up as their cooldown periods end
• This prevents catastrophic memory usage if millions of unique errors occur

For catastrophic scenario protection:

When tracking limit is reached:

• Errors include tracking_limit_reached: true in context
• Errors are still reported to Bugsnag (no silent failures)
• Throttling is bypassed to prevent cache overflow
• Once old errors expire, throttling resumes automatically

Testing

Run the test suite:

Run static analysis:

Requirements

• PHP 8.1 or higher
• Laravel 10.x or 11.x

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Credits

• Nikolay Nesov

License

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