Weave Code
Metrics Laravel Package
directorytree/metrics
Record and query metrics in Laravel with a simple, elegant API. Track page views, API calls, signups, and other countable events. Supports values, categories, custom attributes, hourly/dated metrics, model-based tracking, and Redis storage.
Record metrics in your Laravel application
Frequently asked questions about Metrics
- How do I install and set up DirectoryTree/Metrics in a Laravel 9+ project?
- Run `composer require directorytree/metrics`, publish the migrations with `php artisan vendor:publish --tag=metrics-migrations`, then execute `php artisan migrate`. Optionally, publish the config file for customization using `php artisan vendor:publish --tag=metrics-config`. The package integrates seamlessly with Laravel’s service container and requires no additional dependencies beyond PHP 8.1+.
- Can I track hourly metrics or only daily aggregates?
- Yes, the package supports both hourly and daily metrics. Use `Metrics::capture('event.name', ['hour' => true])` to record hourly granularity. This is useful for real-time dashboards but may require database optimization for high-frequency writes. Hourly metrics are stored as separate rows with `hour` field populated.
- Does DirectoryTree/Metrics work with Laravel’s queue system for background processing?
- Yes, metrics can be committed asynchronously using the `metrics:commit` Artisan command or by dispatching a job. This offloads persistence from the request lifecycle, improving performance for high-traffic applications. The Redis driver also supports distributed processing, making it ideal for microservices or multi-AZ setups.
- How do I associate metrics with Eloquent models (e.g., track actions per user)?
- Use the `HasMetrics` trait on your model. This adds `incrementMetric()` and `decrementMetric()` methods, and metrics are automatically linked via `measurable_type` and `measurable_id` fields. For example, `User::find(1)->incrementMetric('login_attempts')` will record the metric tied to that user.
- What Laravel versions and PHP versions are supported?
- The package supports Laravel 9.0 and above with PHP 8.1 or higher. It leverages Laravel’s modern features like facades, service container, and Eloquent ORM, ensuring compatibility with recent Laravel releases. Always check the [GitHub repository](https://github.com/DirectoryTree/Metrics) for the latest version compatibility.
- How do I test metrics in Laravel’s testing environment?
- Use the built-in fake implementation: `Metrics::fake()`. This allows you to assert captured metrics without persisting them to the database. For example, `Metrics::assertCaptured('event.name', 1)` verifies a metric was recorded. This is critical for unit and integration tests in CI/CD pipelines.
- What are the performance implications of storing hourly metrics at scale?
- Storing hourly metrics can bloat your database, especially for high-frequency events (e.g., 24 rows/day per metric). Monitor table growth and consider indexing the `name`, `year`, `month`, `day`, and `hour` fields. For distributed systems, use Redis to offload writes, but ensure Redis TTL policies align with your retention needs.
- Can I customize the database schema or use a different storage driver?
- Yes, the package provides a flexible architecture. You can extend the `MetricData` model or create a custom repository. For storage, it includes a database driver (default) and a Redis driver. To switch drivers, configure the `metrics.driver` setting in the published config file to `redis` or `database`.
- How do I handle data retention or archiving old metrics?
- The package does not include built-in TTL or archiving. Use Laravel scheduling to run `Metric::whereDate('created_at', '<', now()->subDays(30))->delete()` or similar queries. For long-term retention, export metrics to S3 or another storage system and truncate the database table periodically.
- Are there alternatives to DirectoryTree/Metrics for Laravel metric tracking?
- Alternatives include Laravel Scout for search analytics, Spatie’s Laravel Analytics, or custom solutions using Laravel’s query builder and caching. However, DirectoryTree/Metrics stands out for its Laravel-native integration, support for hourly granularity, custom attributes, and model associations. Evaluate your needs: if you require real-time dashboards or model-based tracking, this package is a strong choice.
Weaver
How can I help you explore Laravel packages today?