Xelentwatch Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require xelent/xelentwatch
   php artisan vendor:publish --tag=xelentwatch-config
   

2. Configure .env:

   XELENTWATCH_ENABLED=true
   XELENTWATCH_TOKEN=your-app-token
   XELENTWATCH_INGEST_URI=your-tcp-server:2407
   

3. Verify: Run php artisan config:clear and test with a manual event:

   use Xelent\Xelentwatch\Facades\Xelentwatch;
   Xelentwatch::event('test_event', ['key' => 'value']);
   

First Use Case: HTTP Request Telemetry

Automatically track request performance by adding to app/Providers/AppServiceProvider.php:

public function boot()
{
    if (config('xelentwatch.enabled')) {
        \Xelent\Xelentwatch\Facades\Xelentwatch::trackRequests();
    }
}

Implementation Patterns

Core Workflows

1. Request Tracking:

   // Enable globally (AppServiceProvider)
   Xelentwatch::trackRequests();
   
   // Or per-route (RouteServiceProvider)
   Xelentwatch::trackRequest($request);
   

2. Artisan Command Monitoring:

   use Xelent\Xelentwatch\Facades\Xelentwatch;
   
   protected function handle()
   {
       Xelentwatch::trackCommand($this);
       // Command logic
   }
   

3. Custom Events:

   Xelentwatch::event('user.created', [
       'user_id' => $user->id,
       'metadata' => ['plan' => $user->plan]
   ]);
   

Integration Tips

• Middleware: Create middleware to track requests:

  public function handle($request, Closure $next)
  {
      Xelentwatch::trackRequest($request);
      return $next($request);
  }
  

• Exception Handling: Log exceptions automatically:

  try {
      // Risky code
  } catch (\Exception $e) {
      Xelentwatch::exception($e);
      throw $e;
  }
  

• Scheduled Tasks: Wrap schedule() calls:

  $schedule->command('backup:run')->everyMinute()
      ->via(function () {
          Xelentwatch::trackCommand(new \Illuminate\Console\Scheduling\Event($this));
      });
  

Sampling Configuration

Adjust sampling rates in config/xelentwatch.php to balance load:

'sampling' => [
    'requests' => 0.5, // 50% of requests
    'exceptions' => 1.0, // All exceptions
],

Gotchas and Tips

Pitfalls

1. TCP Connection Issues:

   • Ensure XELENTWATCH_INGEST_URI is reachable (firewall, Docker networking).
   • Debug with telnet <uri> 2407 or nc -zv <uri> 2407.
   • Fix: Use XELENTWATCH_TIMEOUT (default: 1s) to avoid blocking:

     'ingest' => [
         'timeout' => 2, // 2 seconds
     ],
     

2. Sampling Overhead:

   • High sample rates (e.g., 1.0) may impact performance.
   • Tip: Start with 0.1 for requests/commands, then adjust.

3. Token Leaks:

   • Never expose XELENTWATCH_TOKEN in client-side code or logs.
   • Fix: Use .env validation (Laravel 8+):

     // config/validation.php
     'xelentwatch_token' => 'required_if:xelentwatch_enabled,true',
     

4. Queue Delays:

   • Events sent via queues may arrive out-of-order.
   • Workaround: Use Xelentwatch::event(..., ['sync' => true]) for critical data.

Debugging

• Enable Debug Mode:

  XELENTWATCH_DEBUG=true
  

  Logs payloads to storage/logs/xelentwatch.log.

• Validate Payloads: Check raw TCP output with:

  nc -l 2407 | hexdump -C
  

Extension Points

1. Custom Payloads: Override the payload formatter in app/Providers/XelentwatchServiceProvider.php:

   public function boot()
   {
       Xelentwatch::extendPayload(function ($payload) {
           $payload['custom'] = ['app_version' => '1.0.0'];
           return $payload;
       });
   }
   

2. Batch Processing: For high-volume apps, implement batching:

   Xelentwatch::setBatchSize(100); // Send every 100 events
   Xelentwatch::setBatchTimeout(30); // Flush every 30s
   

3. Environment-Specific Config: Use config/xelentwatch.php overrides:

   return [
       'environment' => env('APP_ENV'),
       'sampling' => [
           'requests' => env('APP_ENV') === 'local' ? 0.0 : 0.5,
       ],
   ];
   

Pro Tips

• Health Checks: Add a /health endpoint that checks telemetry connectivity:

  Route::get('/health', function () {
      try {
          Xelentwatch::ping();
          return response()->json(['status' => 'ok']);
      } catch (\Exception $e) {
          return response()->json(['status' => 'error'], 500);
      }
  });
  

• Retries: Configure retries for transient failures:

  'ingest' => [
      'retries' => 3,
      'retry_delay' => 100, // ms
  ],
  

• Data Sanitization: Strip sensitive data before sending:

  Xelentwatch::filterPayload(function ($payload) {
      unset($payload['data']['password']);
      return $payload;
  });