Lamet Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require itsemon245/lamet
   php artisan lamet:install
   

   This publishes the config file and creates a migration for the metrics table.

2. Run Migrations:

   php artisan migrate
   

3. First Metric:

   use Lamet\Facades\Lamet;
   
   Lamet::record('api.requests', 1); // Increment a counter
   Lamet::record('api.latency', 150); // Record a gauge (ms)
   

4. Verify Data: Check the lamet_metrics table directly or configure Grafana to query it.

First Use Case

Track API request counts and latency:

// In your API middleware or controller
Lamet::record('api.requests', 1);
Lamet::record('api.latency', $executionTimeMs);

Implementation Patterns

Core Workflows

1. Metric Types:

   • Counters: Incremental metrics (e.g., api.requests).
   • Gauges: Point-in-time values (e.g., memory.usage).
   • Timers: Track durations (auto-calculates min/max/avg).

     Lamet::timer('db.query.time')->start();
     // ... DB query ...
     Lamet::timer('db.query.time')->stop();
     

2. Tagging for Context:

   Lamet::record('api.requests', 1, ['endpoint' => 'users.index', 'status' => '200']);
   

3. Bulk Recording:

   Lamet::bulk([
       ['api.requests', 1, ['endpoint' => 'users.create']],
       ['memory.usage', memory_get_usage(true)],
   ]);
   

4. Scheduled Aggregation: Configure lamet:clean in your app/Console/Kernel.php:

   protected function schedule(Schedule $schedule)
   {
       $schedule->command('lamet:clean')->dailyAt('03:00');
   }
   

Integration Tips

• Middleware: Record latency for all requests:

  public function handle($request, Closure $next)
  {
      $start = microtime(true);
      $response = $next($request);
      Lamet::record('http.latency', (microtime(true) - $start) * 1000);
      return $response;
  }
  

• Service Providers: Boot metrics collection:

  public function boot()
  {
      Lamet::record('app.uptime', time());
  }
  

• Grafana: Use the PostgreSQL/MySQL data source with queries like:

  SELECT
      metric,
      tags,
      SUM(value) as total,
      AVG(value) as avg
  FROM lamet_metrics
  WHERE created_at > NOW() - INTERVAL '1 hour'
  GROUP BY metric, tags
  

Gotchas and Tips

Pitfalls

1. Cache Dependencies:

   • Metrics rely on the configured cache driver (default: file). Switching drivers (e.g., to redis) requires:

     php artisan config:clear
     

   • Tip: Use redis for high-throughput apps to avoid disk I/O bottlenecks.

2. Tagging Quirks:

   • Tags are stored as JSON in the DB. Ensure they’re serializable:

     // ❌ Avoid
     Lamet::record('metric', 1, ['tags' => new stdClass()]);
     
     // ✅ Do
     Lamet::record('metric', 1, ['tags' => json_encode(['key' => 'value'])]);
     

3. Timer Precision:

   • Timers use microtime(true). For sub-millisecond precision, ensure your server’s clock is synchronized (e.g., via NTP).

4. Grafana Time Series:

   • Grafana expects timestamps in Unix epoch. Lamet’s created_at is already formatted correctly, but custom queries may need:

     SELECT
         metric,
         tags,
         value,
         EXTRACT(EPOCH FROM created_at) as time
     FROM lamet_metrics
     

Debugging

• Check Raw Data:

  php artisan tinker
  >>> \DB::table('lamet_metrics')->latest()->take(10)->get();
  

• Flush Cache: If metrics aren’t appearing:

  php artisan cache:clear
  php artisan lamet:flush
  

Extension Points

1. Custom Aggregators: Override the default aggregation logic in app/Providers/LametServiceProvider.php:

   public function boot()
   {
       Lamet::extend('custom_metric', function ($value, $tags) {
           return round($value * 1.5); // Example: Scale values
       });
   }
   

2. Event Listeners: Hook into metric recording via events (not yet documented; check lamet:install for event hooks):

   Lamet::listen('metric.recorded', function ($metric, $value, $tags) {
       Log::info("Metric recorded: {$metric} = {$value}");
   });
   

3. Database Schema: Extend the lamet_metrics table by publishing and modifying the migration:

   php artisan vendor:publish --tag=lamet-migrations