Filament Route Statistics Laravel Package

Technical Evaluation

Architecture Fit

• Leverages existing Laravel ecosystem: The package integrates seamlessly with Laravel’s built-in routing system and Filament 3’s plugin architecture, making it a natural fit for Laravel-based applications requiring observability.
• Stateless design: Since it relies on bilfeldt/laravel-route-statistics (which uses middleware to track route hits), it imposes minimal overhead on application logic.
• UI-first approach: Provides a dedicated Filament page for route analytics, reducing the need for custom dashboards or third-party tools.

Integration Feasibility

• Low coupling: The package is a plugin, meaning it doesn’t modify core Laravel or Filament behavior. It only adds a UI layer over existing route statistics.
• Dependency alignment: Requires bilfeldt/laravel-route-statistics (v3+), which must be installed separately. This adds a minor dependency but is justified by the core functionality.
• Filament 3 compatibility: Explicitly designed for Filament 3, ensuring alignment with modern Laravel admin panel patterns.

Technical Risk

• Middleware dependency: Route statistics rely on middleware execution, which could introduce performance overhead if not configured optimally (e.g., excluding health checks or API routes).
• Data persistence: The underlying laravel-route-statistics package uses a route_statistics table. Schema migrations must be handled carefully to avoid conflicts in shared environments.
• Limited customization: The plugin’s UI is opinionated (charts, tables). Extending or modifying visualizations may require forking or custom CSS/JS.
• No built-in retention policy: Route statistics data could grow unbounded without cleanup mechanisms (e.g., TTL policies).

Key Questions

1. Performance impact: How will route tracking affect production traffic? Are there routes (e.g., cron jobs, webhooks) that should be excluded?
2. Data retention: What cleanup strategy exists for historical route statistics? Will manual pruning be required?
3. Access control: How should route statistics be secured? Should certain teams (e.g., DevOps) have read-only access?
4. Alerting: Can the plugin trigger alerts (e.g., Slack) for anomalous route usage (e.g., sudden spikes)?
5. Multi-tenant support: If using Laravel’s multi-tenancy, how will route statistics be scoped per tenant?
6. Testing coverage: Does the package include tests for edge cases (e.g., route caching, middleware failures)?

Integration Approach

Stack Fit

• Laravel + Filament 3: Native fit due to plugin architecture and shared dependencies.
• PHP 8.1/8.2: Aligns with modern Laravel/Lumen requirements.
• Database: Requires a route_statistics table (supports MySQL, PostgreSQL, SQLite). No additional DB changes needed beyond the package’s migrations.
• Frontend: Uses Filament’s Blade/Inertia-based UI. No custom frontend build tools required.

Migration Path

1. Prerequisite setup:
   • Install bilfeldt/laravel-route-statistics (v3+):

     composer require bilfeldt/laravel-route-statistics
     php artisan vendor:publish --provider="Bilfeldt\RouteStatistics\RouteStatisticsServiceProvider"
     

   • Configure middleware in app/Http/Kernel.php:

     protected $middlewareGroups = [
         'web' => [
             // ...
             \Bilfeldt\RouteStatistics\Middleware\RecordRoute::class,
         ],
     ];
     

2. Plugin installation:
   • Install the Filament plugin:

     composer require amendozaaguiar/filament-route-statistics
     php artisan vendor:publish --tag="filament-route-statistics-translations"
     

   • Register the plugin in Filament/AdminPanelProvider.php:

     ->plugins([
         \Amendozaaguiar\FilamentRouteStatistics\FilamentRouteStatisticsPlugin::make(),
     ])
     

3. Post-install validation:
   • Verify the route_statistics table exists.
   • Test route tracking by accessing routes and checking the Filament page.

Compatibility

• Filament versions: Explicitly for Filament 3.x. May require updates for Filament 4+.
• Laravel versions: Tested on Laravel 10/11 (PHP 8.1/8.2). Backward compatibility with Laravel 9 may need verification.
• Custom route models: If using API resources or custom route models, ensure laravel-route-statistics is configured to handle them (e.g., via RouteStatistics::ignore()).

Sequencing

1. Phase 1 (Core Setup):
   • Install dependencies and configure middleware.
   • Publish translations and migrations.
2. Phase 2 (UI Integration):
   • Register the plugin in the Filament panel.
   • Customize access control (e.g., via Filament’s built-in policies).
3. Phase 3 (Optimization):
   • Exclude non-critical routes from tracking.
   • Implement data retention policies (e.g., scheduled DB cleanup).
4. Phase 4 (Monitoring):
   • Set up alerts for unusual route activity.
   • Integrate with existing observability tools (e.g., Prometheus).

Operational Impact

Maintenance

• Dependency updates: Monitor bilfeldt/laravel-route-statistics and amendozaaguiar/filament-route-statistics for breaking changes.
• Schema changes: The route_statistics table may evolve. Use Laravel migrations to manage updates.
• Plugin updates: Filament plugin updates may require re-registering or minor config tweaks.

Support

• Troubleshooting:
  • No data appearing: Verify middleware is registered and routes are being hit.
  • Performance issues: Check for excluded routes or high-traffic endpoints.
  • UI errors: Clear Filament cache (php artisan filament:cache:clear) or check for CSS/JS conflicts.
• Vendor support: Limited to GitHub issues. May need to fork for critical fixes.

Scaling

• High-traffic routes: Middleware overhead is minimal (~1ms per request), but test under load. Consider excluding /health or /ping routes.
• Database scaling: Route statistics table growth can be managed with:
  • Regular TRUNCATE or DELETE operations (e.g., retain last 30 days).
  • Partitioning the table by date (advanced).
• Multi-server deployments: Ensure all app servers share the same DB to aggregate stats accurately.

Failure Modes

Ramp-Up

• Developer onboarding:
  • Document middleware configuration and excluded routes.
  • Provide screenshots of the Filament page for reference.
• Performance tuning:
  • Benchmark middleware impact on critical paths.
  • Identify top routes by hits to prioritize optimization.
• Access control:
  • Restrict the Filament page to admin or observability roles.
  • Use Filament’s built-in policies to gate access.
• Alerting setup:
  • Example: Alert if a route’s hit count exceeds 90th percentile.
  • Integrate with Laravel Horizon or external tools (e.g., Datadog).