Metrics Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require directorytree/metrics
   php artisan vendor:publish --tag="metrics-migrations"
   php artisan migrate
   

2. First Metric:

   use DirectoryTree\Metrics\Facades\Metrics;
   Metrics::record('page_views'); // or metric('page_views')->record();
   

3. Querying:

   $views = Metric::today()->where('name', 'page_views')->sum('value');
   

Where to Look First

• Facade/Helper: Metrics facade or metric() helper for recording.
• Query Builder: Metric model for querying (e.g., today(), thisMonth()).
• Configuration: config/metrics.php for driver (e.g., redis) and queue settings.

First Use Case

Track page views in a Laravel controller:

use DirectoryTree\Metrics\Facades\Metrics;

public function show(Page $page) {
    Metrics::record('page_views');
    return view('page', ['page' => $page]);
}

Implementation Patterns

Core Workflows

1. Recording Metrics:

   • Basic: metric('name')->record() (default value = 1).
   • Bulk: metric('api_calls')->record(10).
   • Categorized: metric('errors')->category('critical')->record().

2. Model Association:

   // User model
   use DirectoryTree\Metrics\HasMetrics;
   class User extends Model { use HasMetrics; }
   
   // Record
   metric('user_logins')->measurable($user)->record();
   // Query
   $user->metrics()->where('name', 'user_logins')->sum('value');
   

3. Time-Based Granularity:

   • Daily (default): metric('daily_views')->record().
   • Hourly: metric('hourly_views')->hourly()->record().

4. Custom Attributes:

   metric('views')
       ->with(['source' => 'google', 'country' => 'US'])
       ->record();
   

Integration Tips

• Middleware: Record metrics in middleware (e.g., track API calls):

  public function handle(Request $request, Closure $next) {
      metric('api_requests')->record();
      return $next($request);
  }
  

• Events: Hook into Laravel events (e.g., registered):

  Event::listen('registered', function () {
      metric('user_signups')->record();
  });
  

• Jobs: Batch metrics in queues:

  Metrics::capture();
  // ... record metrics ...
  Metrics::commit(); // or auto-commit on job completion
  

Performance Patterns

• Redis Driver: Use for high-traffic apps:

  // config/metrics.php
  'driver' => 'redis',
  

  Schedule metrics:commit hourly in app/Console/Kernel.php.
• Batching: Capture and commit in bulk:

  Metrics::capture();
  // ... record 100+ metrics ...
  Metrics::commit();
  

Gotchas and Tips

Pitfalls

1. Hourly Metrics Overuse:

   • Hourly metrics create 24x more rows than daily. Use sparingly.
   • Fix: Reserve for critical time-sensitive metrics (e.g., real-time analytics).

2. Auto-Commit Conflicts:

   • If using redis driver, disable auto_commit in config:

     'auto_commit' => false,
     

   • Fix: Schedule metrics:commit manually.

3. Custom Attributes Uniqueness:

   • Metrics with identical name + attributes are merged (values summed).
   • Fix: Ensure attributes like source are unique if segmentation is needed.

4. Model Association Quirks:

   • measurable() requires the model to use HasMetrics trait.
   • Fix: Add trait to model or use raw IDs:

     metric('user_actions')->measurable_id($user->id)->measurable_type('App\Models\User')->record();
     

Debugging

• Missing Metrics:
  • Check if auto_commit is enabled (metrics may not persist if using redis).
  • Debug: Run php artisan metrics:commit manually.
• Query Performance:
  • Avoid get() on large datasets; use sum() or count():

    // Bad (loads all rows)
    Metric::today()->get();
    // Good
    Metric::today()->sum('value');
    

Extension Points

1. Custom Metric Models:

   • Extend DirectoryTree\Metrics\Metric for additional fields:

     class CustomMetric extends Metric {
         protected $casts = ['ip_address' => 'string'];
     }
     

   • Bind in AppServiceProvider:

     Metrics::extend('custom', function () {
         return new CustomMetric();
     });
     

2. Custom Repository:

   • Override DirectoryTree\Metrics\MetricRepository for custom logic (e.g., caching):

     Metrics::setRepository(new CustomMetricRepository());
     

3. Testing:

   • Use the fake:

     Metrics::fake();
     metric('test')->record();
     Metrics::assertRecorded('test');
     

Config Quirks

• Redis TTL:
  • Default TTL for Redis is 1 day (metrics.ttl in config).
  • Tip: Adjust for high-latency environments (e.g., metrics.ttl = 2).
• Queue Connection:
  • If using queues, specify in config:

    'queue_connection' => 'redis',
    

Pro Tips

• Backfilling Data: Use date() to populate historical metrics:

  metric('signups')->date(Carbon::parse('2023-01-01'))->record(100);
  

• Segmented Analytics: Combine category + attributes for multi-dimensional tracking:

  metric('purchases')
      ->category('product_x')
      ->with(['country' => 'US', 'device' => 'mobile'])
      ->record();
  

• Laravel Scout Integration: Index metrics for full-text search:

  Metric::searchable(['name', 'category'])->toSearchableArray();