Sam Monitoring Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require canaltp/sam-monitoring
   

   Publish the configuration (if needed):

   php artisan vendor:publish --provider="CanalTP\SamMonitoring\SamMonitoringServiceProvider"
   

2. Basic Usage Register a monitorable model (e.g., User):

   use CanalTP\SamMonitoring\Traits\Monitorable;
   
   class User extends Model
   {
       use Monitorable;
   }
   

3. First Monitoring Event Trigger a monitorable event (e.g., login attempt):

   $user = User::find(1);
   $user->monitor('login_attempt', ['ip' => request()->ip()]);
   

4. Viewing Logs Access logs via:

   php artisan sam:logs
   

   Or check the sam_monitoring_logs table directly.

Implementation Patterns

Common Workflows

1. Event-Based Monitoring Attach monitoring to Eloquent events (e.g., retrieved, saved):

   User::retrieved(function ($user) {
       $user->monitor('retrieved', ['context' => 'dashboard']);
   });
   

2. API Request Tracking Log API calls with metadata:

   Route::get('/api/data', function () {
       auth()->user()->monitor('api_call', [
           'endpoint' => 'data',
           'method' => 'GET',
           'params' => request()->all()
       ]);
       return response()->json(['data' => '...']);
   });
   

3. Batch Processing Monitor bulk operations (e.g., imports):

   $users = User::all();
   foreach ($users as $user) {
       $user->monitor('batch_import', ['batch_id' => 123]);
   }
   

4. Custom Log Storage Extend storage via SamMonitoringServiceProvider:

   $this->app->bind('sam.monitoring.storage', function () {
       return new CustomStorage();
   });
   

Integration Tips

• Laravel Events: Tie monitoring to existing events (e.g., auth.login):

  event(new Authenticated($user));
  $user->monitor('authenticated', ['event' => 'login']);
  

• Middleware: Log requests globally:

  class MonitorRequests
  {
      public function handle($request, Closure $next)
      {
          auth()->user()->monitor('request', [
              'path' => $request->path(),
              'method' => $request->method()
          ]);
          return $next($request);
      }
  }
  

• Queue Jobs: Defer monitoring for performance:

  $user->monitor('job_started', ['job' => 'export'])->dispatch();
  

Gotchas and Tips

Pitfalls

1. Performance Overhead

   • Avoid monitoring in tight loops (e.g., User::all()->each(...)).
   • Use queues for bulk operations:

     User::chunk(100, function ($users) {
         foreach ($users as $user) {
             $user->monitor('chunk_processed')->dispatch();
         }
     });
     

2. Missing Traits

   • Ensure Monitorable trait is used on the model:

     class User extends Model
     {
         // ❌ Forgotten trait = no monitoring!
     }
     

3. Configuration Conflicts

   • Default log table: sam_monitoring_logs. Customize in config/sam-monitoring.php:

     'table' => 'custom_monitoring_logs',
     

4. Race Conditions

   • If monitoring is critical, use transactions:

     DB::transaction(function () use ($user) {
         $user->monitor('critical_action');
     });
     

Debugging

• Log Not Appearing? Check:

  • Database connection.
  • Table permissions (sam_monitoring_logs).
  • Trait usage on the model.
  • Queue workers (if using dispatch()).

• Query Debugging Enable Laravel debug mode:

  APP_DEBUG=true
  

  Or log raw queries:

  \DB::enableQueryLog();
  $user->monitor('test');
  dd(\DB::getQueryLog());
  

Extension Points

1. Custom Log Fields Override the getMonitorableAttributes() method:

   class User extends Model
   {
       use Monitorable;
   
       protected function getMonitorableAttributes()
       {
           return array_merge(parent::getMonitorableAttributes(), [
               'custom_field' => $this->custom_field,
           ]);
       }
   }
   

2. Log Filters Filter logs via a scope:

   class UserMonitoringScope
   {
       public function apply(Builder $builder, $event)
       {
           return $builder->where('event', $event);
       }
   }
   

   Register in SamMonitoringServiceProvider:

   $this->app->bind('sam.monitoring.scopes', function () {
       return [UserMonitoringScope::class];
   });
   

3. Webhook Notifications Extend the Logged event:

   event(new \CanalTP\SamMonitoring\Events\Logged($log));
   // Send to Slack/email in a listener.