directorytree / metrics
Record metrics in your Laravel application
Installs: 646
Dependents: 0
Suggesters: 0
Security: 0
Stars: 156
Watchers: 0
Forks: 2
Open Issues: 1
pkg:composer/directorytree/metrics
Requires
- illuminate/collections: ^9.0|^10.0|^11.0|^12.0
- illuminate/database: ^9.0|^10.0|^11.0|^12.0
- illuminate/redis: ^9.0|^10.0|^11.0|^12.0
- illuminate/support: ^9.0|^10.0|^11.0|^12.0
Requires (Dev)
- laravel/pint: ^1.0
- orchestra/testbench: ^7.0|^8.0|^9.0|^10.0
- pestphp/pest: ^1.0|^2.0|^3.0
This package is auto-updated.
Last update: 2025-10-23 03:30:53 UTC
README
A simple and elegant way to record metrics in your Laravel application.
Metrics provides a simple, elegant way to record and query metrics in your Laravel application.
Track page views, API calls, user signups, or any other countable events.
Index
Requirements
- PHP >= 8.1
- Laravel >= 9.0
Installation
You may install the package via composer:
composer require directorytree/metrics
Then, publish the migrations:
php artisan vendor:publish --tag="metrics-migrations"
Finally, run the migrations:
php artisan migrate
Setup
Optionally, you may publish the configuration file:
php artisan vendor:publish --tag="metrics-config"
This will create a config/metrics.php file where you may configure the driver and queueing behavior.
Using the Redis Driver
For distributed applications or high-traffic scenarios, you may use the redis driver to store captured metrics in Redis before committing them to the database in batches.
First, set the driver to redis in your configuration:
// config/metrics.php return [ 'driver' => 'redis', // ... ];
Or via environment variable:
METRICS_DRIVER=redis
Then, you may schedule the metrics:commit command to periodically commit metrics from Redis to your database:
Important
Remember to disable auto_commit in the configuration file if you plan on committing metrics using the commit command.
// app/Console/Kernel.php protected function schedule(Schedule $schedule): void { $schedule->command('metrics:commit')->hourly(); }
You may also run the command manually:
php artisan metrics:commit
This approach provides reduced database load since metrics can be committed in bulk at an expected interval instead of at the end of the request life-cycle.
The Redis driver uses a hash to store pending metrics with a configurable TTL (default of 1 day). This ensures metrics are eventually committed even if the scheduled command fails temporarily.
Usage
Recording Metrics
Record a metric using the Metrics facade:
use DirectoryTree\Metrics\MetricData; use DirectoryTree\Metrics\Facades\Metrics; Metrics::record(new MetricData('signups'));
Or using the metric global helper:
metric('signups')->record();
Or using the PendingMetric class:
use DirectoryTree\Metrics\PendingMetric; PendingMetric::make('signups')->record();
Which ever method you use, metrics are recorded in the same way. Use whichever you prefer.
For the rest of the documentation, we will use the metric helper for consistency and brevity.
Recording with Values
By default, metrics have a value of 1. You may specify a custom value in the record method:
// Track multiple API calls at once metric('api:requests')->record(10); // Track batch job completions metric('jobs:completed')->record(250);
If you record the same metric multiple times, the values will be summed:
metric('auth:logins')->record(); // value: 1 metric('auth:logins')->record(); // value: 1 // Database will contain one metric with value: 2
Recording with Categories
Organize metrics into categories:
// Track API calls by endpoint metric('api:requests')->category('users')->record(); metric('api:requests')->category('orders')->record(); // Track errors by severity metric('app:errors')->category('critical')->record(); metric('app:errors')->category('warning')->record(); // Track purchases by payment method metric('purchases')->category('stripe')->record(); metric('purchases')->category('paypal')->record();
These will be stored as separate metrics, allowing you to track the same metric across different contexts.
Recording with Dates
By default, metrics are recorded with today's date. You may specify a custom date using the date method:
use Carbon\Carbon; // Backfill signup data from an import metric('signups') ->date(Carbon::parse('2025-01-15')) ->record(50); // Record yesterday's batch job completions metric('jobs:completed') ->date(Carbon::yesterday()) ->record(1250);
Recording Hourly Metrics
By default, metrics are recorded at the daily level. For metrics that require hour-level granularity, you may use the hourly() method:
// Track API requests by hour metric('api:requests') ->hourly() ->record();
Hourly metrics include the hour (0-23) in addition to the year, month, and day, allowing you to track metrics at a more granular level:
use Carbon\Carbon; // Record API requests for a specific hour metric('api:requests') ->date(Carbon::parse('2025-10-19 14:30:00')) ->hourly() ->record(); // This will be stored with hour = 14
Hourly metrics are stored separately from daily metrics, even for the same metric name:
metric('page:views')->record(); // Daily metric (hour = null) metric('page:views')->hourly()->record(); // Hourly metric (hour = current hour)
You can query hourly metrics using the thisHour(), lastHour(), and onDateTime() methods:
use DirectoryTree\Metrics\Metric; // Get metrics for this hour $metrics = Metric::thisHour()->get(); // Get metrics for last hour $metrics = Metric::lastHour()->get(); // Get metrics for a specific date and hour $metrics = Metric::onDateTime(Carbon::parse('2025-10-19 14:00:00'))->get(); // Get API requests for the current hour $requests = Metric::thisHour() ->where('name', 'api:requests') ->sum('value');
Tip
Use hourly metrics sparingly, as they create 24x more database rows than daily metrics. Reserve hourly tracking for metrics that genuinely benefit from hour-level granularity.
Recording for Models
Associate metrics with Eloquent models using the HasMetrics trait:
use DirectoryTree\Metrics\HasMetrics; use Illuminate\Database\Eloquent\Model; class User extends Model { use HasMetrics; }
Then record metrics for a specific model:
// Track logins per user metric('auth:logins') ->measurable(Auth::user()) ->record(); // Track orders per customer metric('orders') ->measurable(Customer::find(...)) ->record(); // Track API calls per client metric('api:requests') ->measurable(ApiClient::find(...)) ->record();
Query metrics for a model:
// Get total logins for a user $totalLogins = $user->metrics() ->where('name', 'auth:logins') ->sum('value'); // Get orders this month for a customer $ordersThisMonth = $customer->metrics() ->where('name', 'orders') ->thisMonth() ->sum('value');
Recording with Custom Attributes
Store additional context with your metrics by adding custom attributes. This is useful for segmenting metrics by various dimensions like source, country, device type, or any other custom data.
First, create a migration to add custom columns to the metrics table:
use Illuminate\Database\Schema\Blueprint; use Illuminate\Support\Facades\Schema; Schema::table('metrics', function (Blueprint $table) { $table->string('source')->nullable()->index(); $table->string('country')->nullable()->index(); $table->string('device')->nullable(); });
Then, use the with() method to record metrics with custom attributes:
// Track post views with traffic source metric('views') ->measurable(Post::find(1)) ->with(['source' => 'google']) ->record(); // Track conversions with multiple attributes metric('conversions') ->with([ 'source' => 'facebook', 'country' => 'US', 'device' => 'mobile', ]) ->record(); // Track API requests for a user within a team metric('api:requests') ->measurable(Auth::user()) ->with(['team_id' => 123]) ->record();
Custom attributes are included in the metric's uniqueness check, meaning metrics with different attribute values are stored separately:
metric('page:views')->with(['source' => 'google'])->record(); // Creates metric #1 metric('page:views')->with(['source' => 'facebook'])->record(); // Creates metric #2 metric('page:views')->with(['source' => 'google'])->record(); // Increments metric #1
This allows you to segment and analyze metrics by any dimension:
// Get page views by source $googleViews = Metric::where('name', 'page:views') ->where('source', 'google') ->sum('value'); // Get conversions by country this month $conversions = Metric::thisMonth() ->where('name', 'conversions') ->get() ->groupBy('country') ->map->sum('value'); // Get mobile vs desktop traffic $mobileViews = Metric::today() ->where('name', 'page:views') ->where('device', 'mobile') ->sum('value');
You can also use custom attributes with the MetricData class:
use DirectoryTree\Metrics\MetricData; use DirectoryTree\Metrics\Facades\Metrics; Metrics::record(new MetricData( name: 'page:views', additional: [ 'source' => 'google', 'country' => 'US', ] ));
Or with the PendingMetric class:
use DirectoryTree\Metrics\PendingMetric; PendingMetric::make('page:views') ->with(['source' => 'google', 'country' => 'US']) ->record();
Important
Core metric attributes (name, category, year, month, day, measurable_type, measurable_id, value) cannot be overridden via custom attributes. They are protected and will always use the values set through their respective methods.
Capturing & Committing
For high-performance scenarios, you may capture metrics in memory and commit them in batches:
use DirectoryTree\Metrics\Facades\Metrics; Metrics::capture(); // Record multiple metrics... metric('signups')->record(); metric('notifications:sent')->category('welcome')->record(); metric('signups')->record(); // Commit all captured metrics at once Metrics::commit();
Captured metrics are automatically committed when the application terminates. You may also stop capturing manually:
Metrics::stopCapturing();
To enable capturing for your entire application, start capturing in your AppServiceProvider:
// app/Providers/AppServiceProvider.php use DirectoryTree\Metrics\Facades\Metrics; class AppServiceProvider extends ServiceProvider { // ... public function boot(): void { Metrics::capture(); } }
This will batch all metrics recorded during the request and commit them automatically when the application terminates, reducing database queries and improving performance.
Querying Metrics
The Metric model includes a powerful query builder with date filtering methods:
use DirectoryTree\Metrics\Metric; // Get today's metrics $metrics = Metric::today()->get(); // Get this week's metrics $metrics = Metric::thisWeek()->get(); // Get this month's metrics $metrics = Metric::thisMonth()->get(); // Get this year's metrics $metrics = Metric::thisYear()->get(); // Get yesterday's metrics $metrics = Metric::yesterday()->get(); // Get last week's metrics $metrics = Metric::lastWeek()->get(); // Get last month's metrics $metrics = Metric::lastMonth()->get(); // Get last year's metrics $metrics = Metric::lastYear()->get(); // Get metrics between specific dates $metrics = Metric::betweenDates( Carbon::parse('2025-01-01'), Carbon::parse('2025-12-31') )->get(); // Get metrics on a specific date $metrics = Metric::onDate(Carbon::parse('2025-10-15'))->get();
Chain with standard Eloquent methods:
// Get today's signups $signups = Metric::today() ->where('name', 'signups') ->sum('value'); // Get this week's purchases $purchases = Metric::thisWeek() ->where('name', 'purchases') ->sum('value'); // Get API usage by endpoint this month $apiUsage = Metric::thisMonth() ->where('name', 'api:requests') ->get() ->groupBy('category') ->map->sum('value'); // Count unique metrics recorded today $count = Metric::today()->count();
Testing
Metrics includes a fake implementation for testing:
use DirectoryTree\Metrics\Measurable; use DirectoryTree\Metrics\Facades\Metrics; public function test_user_signup_records_metric() { Metrics::fake(); // Your code that records metrics... $this->post('register', [ 'email' => 'user@example.com', 'password' => 'password', ]); // Assert metrics were recorded Metrics::assertRecorded('signups'); } public function test_api_call_records_metric_with_endpoint() { Metrics::fake(); $this->getJson('api/users'); // Assert metrics were recorded with a closure Metrics::assertRecorded(fn (Measurable $metric) => $metric->name() === 'api:requests' && $metric->category() === 'users' ); } public function test_failed_login_records_metric() { Metrics::fake(); $this->post('login', [ 'email' => 'wrong@example.com', 'password' => 'wrong', ]); // Assert metrics were not recorded Metrics::assertNotRecorded('auth:logins'); // Assert failed login was recorded Metrics::assertRecorded('auth:attempts'); } public function test_purchase_records_metric_for_user() { Metrics::fake(); $user = User::factory()->create(); $this->actingAs($user)->post('purchases', [ 'product_id' => 1, ]); // Assert metrics were recorded with model Metrics::assertRecorded(fn ($metric) => $metric->name() === 'purchases' && $metric->measurable()?->is($user) ); } public function test_batch_job_records_metrics() { Metrics::fake(); // Run your batch job Artisan::call('orders:process'); // Assert metrics were recorded a specific number of times Metrics::assertRecordedTimes('orders:processed', 100); }
Access recorded metrics in tests:
Metrics::fake(); metric('api:requests')->category('users')->record(); // Get all recorded metrics $all = Metrics::recorded(); // Get metrics by name $apiCalls = Metrics::recorded('api:requests'); // Get metrics with a closure $userEndpoint = Metrics::recorded(fn ($metric) => $metric->category() === 'users' );
Extending & Customizing
Custom Metric Manager
Create your own metric manager by implementing the MetricManager interface:
namespace App\Metrics; use DirectoryTree\Metrics\Measurable; use DirectoryTree\Metrics\MetricManager; class CustomMetricManager implements MetricManager { public function record(Measurable $metric): void { // Your custom recording logic... } public function commit(): void { // Your custom commit logic... } public function capture(): void { // Your custom capture logic... } public function isCapturing(): bool { // Your custom capturing check... } public function stopCapturing(): void { // Your custom stop capturing logic... } }
Then bind it in your AppServiceProvider:
use App\Metrics\CustomMetricManager; use DirectoryTree\Metrics\MetricManager; public function register(): void { $this->app->singleton(MetricManager::class, CustomMetricManager::class); }
Custom Metric Repository
Create a custom repository for storing captured metrics:
namespace App\Metrics; use DirectoryTree\Metrics\Measurable; use DirectoryTree\Metrics\MetricRepository; class CustomMetricRepository implements MetricRepository { public function add(Measurable $metric): void { // Your custom add logic... } public function all(): array { // Your custom retrieval logic... } public function flush(): void { // Your custom flush logic... } }
Then bind it in your AppServiceProvider:
use App\Metrics\CustomMetricRepository; use DirectoryTree\Metrics\MetricRepository; public function register(): void { $this->app->singleton(MetricRepository::class, CustomMetricRepository::class); }