Sdk Php Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require allstak/sdk-php
   

2. Environment Variables (.env):

   ALLSTAK_API_KEY=ask_live_your_key_here
   ALLSTAK_ENVIRONMENT=local  # or 'production'
   ALLSTAK_RELEASE=myapp@1.0.0
   

3. First Use Case:
   • Laravel auto-discovers the package. No manual registration needed for Laravel 5.5+.
   • For manual registration (older Laravel):

     // config/app.php
     'providers' => [
         AllStak\Laravel\AllStakServiceProvider::class,
     ],
     

   • Test with a manual capture:

     use AllStak\Facade;
     Facade::captureError(new RuntimeException('Test error'));
     Facade::captureLog('info', 'Test log', ['key' => 'value']);
     

Key Starting Points

• Auto-Captured Data: Exceptions, HTTP requests (inbound/outbound), DB queries, cron jobs, and logs.
• Configuration: Override defaults in config/allstak.php or via environment variables (e.g., ALLSTAK_CAPTURE_EXCEPTIONS=false).
• Facade Methods:
  • Facade::captureError(Exception $e)
  • Facade::captureLog(string $level, string $message, array $context)
  • Facade::captureMessage(string $message, array $context)

Implementation Patterns

Core Workflows

1. Observability for HTTP Requests

• Inbound Requests: Automatically captured via Laravel middleware. No manual instrumentation needed.

  // config/allstak.php
  'collectors' => [
      'http' => [
          'enabled' => true,
          'capture_body' => true, // Capture request/response bodies (default: false)
      ],
  ],
  

• Outbound Requests (Guzzle):

  $client = new \GuzzleHttp\Client([
      'handler' => \AllStak\Laravel\Guzzle\AllStakHandler::create(),
  ]);
  

• Manual Outbound Capture:

  Facade::captureHttpRequest('GET', 'https://api.example.com', [
      'headers' => ['Authorization' => 'Bearer token'],
      'body' => ['key' => 'value'],
  ]);
  

2. Database Query Telemetry

• Auto-captured for PDO and Eloquent queries. Toggle via config:

  'collectors' => [
      'pdo' => ['enabled' => true],
      'eloquent' => ['enabled' => true],
  ],
  

• Manual Query Capture:

  Facade::captureQuery('SELECT * FROM users', ['bindings' => [1]], 123);
  

3. Error and Log Handling

• Exceptions: Auto-captured via Laravel’s exception handler. Override the handler in app/Exceptions/Handler.php:

  public function report(Throwable $exception)
  {
      if (!app()->bound('telescope')) {
          Facade::captureError($exception);
      }
      parent::report($exception);
  }
  

• Manual Logs:

  Facade::captureLog('error', 'Failed to process order', ['order_id' => 123]);
  // Or integrate with Monolog:
  $logger->pushHandler(new \AllStak\Laravel\Monolog\AllStakHandler());
  

4. Cron Job Monitoring

• Auto-captured via Laravel’s schedule:run command. Manually trigger:

  Facade::captureCronJob('daily-backup', 'Backup completed', ['status' => 'success']);
  

5. Custom Metrics and Traces

• Metrics:

  Facade::captureMetric('orders.processed', 42, ['status' => 'success']);
  

• Traces (for distributed tracing):

  $trace = Facade::startTrace('user_checkout');
  try {
      // Business logic
  } finally {
      $trace->end();
  }
  

Integration Tips

• Laravel Queues: Auto-captured. For custom queues, wrap jobs in a trace:

  $trace = Facade::startTrace('process_payment');
  PaymentJob::dispatch($order);
  $trace->end();
  

• API Clients: Use the Guzzle handler for outbound HTTP. For other clients (e.g., Symfony HTTP Client), manually capture requests.
• Testing: Disable collectors in tests:

  config(['allstak.collectors.exceptions.enabled' => false]);
  

• Environment-Specific Config: Use config/allstak.php for environment-specific toggles:

  'collectors' => env('APP_ENV') === 'local' ? [
      'http' => ['enabled' => false],
  ] : [],
  

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Issue: Capturing request/response bodies (capture_body: true) can slow down high-traffic endpoints.
   • Fix: Disable for production or use selectively:

     'collectors' => [
         'http' => [
             'enabled' => true,
             'capture_body' => env('APP_ENV') !== 'production',
         ],
     ],
     

2. Sensitive Data Leakage:

   • Issue: Auto-captured logs/errors may include sensitive data (e.g., passwords, tokens).
   • Fix:
     • Redact sensitive fields manually:

       Facade::captureLog('info', 'Login attempt', [
           'user_id' => 123,
           'ip' => request()->ip(),
           'password' => '[REDACTED]', // Always redact!
       ]);
       

     • Use ALLSTAK_IGNORE_KEYS env var to auto-redact keys:

       ALLSTAK_IGNORE_KEYS=password,token,api_key
       

3. Double Instrumentation:

   • Issue: Using both the SDK and another observability tool (e.g., Laravel Telescope) may cause duplicate data.
   • Fix: Disable overlapping collectors or use the SDK as the single source of truth.

4. Guzzle Handler Conflicts:

   • Issue: If using multiple Guzzle clients, the AllStakHandler may not be applied to all.
   • Fix: Ensure all clients use the handler:

     $client = new \GuzzleHttp\Client([
         'handler' => \AllStak\Laravel\Guzzle\AllStakHandler::create(),
     ]);
     

5. Cron Job Auto-Detection:

   • Issue: Not all cron jobs are auto-detected (e.g., custom Artisan commands).
   • Fix: Manually capture cron jobs:

     Facade::captureCronJob('custom-command', 'Command executed', ['status' => 'success']);
     

Debugging

• Check Captured Data:

  • Use the AllStak dashboard to verify data is being sent.
  • Enable debug logs:

    ALLSTAK_DEBUG=true
    

  • Check the allstak log channel in Laravel:

    Log::channel('allstak')->debug('Test debug message');
    

• Network Issues:

  • If data isn’t appearing, verify the API key and network connectivity:

    curl -X POST https://api.allstak.com/v1/events \
         -H "Authorization: Bearer $ALLSTAK_API_KEY" \
         -H "Content-Type: application/json" \
         -d '{}'
    

• Configuration Overrides:

  • Ensure environment variables take precedence over config/allstak.php:

    // config/allstak.php
    'api_key' => env('ALLSTAK_API_KEY', 'fallback_key'),
    

Extension Points

1. Custom Collectors:

   • Extend the SDK by creating a custom collector:

     use AllStak\CollectorInterface;
     
     class CustomCollector implements CollectorInterface {
         public function capture(array $data) {
             // Send data to AllStak
             Facade::send($data);
         }
     }
     

   • Register it in the service provider:

     $this->app->bind(CollectorInterface::class, function () {
         return new CustomCollector();
     });
     

2. Middleware for HTTP Capture:

   • Extend the auto-captured HTTP data by adding middleware:

     namespace App\Http\Middleware;
     
     use AllStak\Facade;
     use Closure;
     
     class AllStakEnrichment {
         public function handle($request, Closure $next) {
             $response = $next($request);
             Facade::captureHttpMetadata('