Inspector Php Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require inspector-apm/inspector-php
   

   Add the service provider to config/app.php:

   'providers' => [
       InspectorApm\InspectorApmServiceProvider::class,
   ],
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="InspectorApm\InspectorApmServiceProvider" --tag="config"
   

   Update config/inspector-apm.php with your API key and application name.

3. First Use Case Enable auto-instrumentation in config/inspector-apm.php:

   'auto_instrument' => true,
   

   Restart your Laravel app. The package will now automatically track:

   • HTTP requests (routes, controllers, middleware)
   • Database queries (Eloquent, Query Builder)
   • Exceptions and errors
   • Background jobs (if using Laravel Queues)

   Verify in the Inspector Dashboard under Services > Your App.

Implementation Patterns

Core Workflows

1. Manual Instrumentation Explicitly track custom spans (e.g., third-party APIs, business logic):

   use InspectorApm\Facades\Inspector;
   
   Inspector::startSpan('custom_operation', function () {
       // Your code here
       sleep(1); // Simulate work
   });
   

2. Middleware Integration Add custom metadata to requests:

   use InspectorApm\Facades\Inspector;
   
   public function handle($request, Closure $next)
   {
       Inspector::setAttribute('user_id', auth()->id());
       return $next($request);
   }
   

3. Database Query Tagging Tag specific queries for debugging:

   DB::table('users')->where('active', 1)->get(['id', 'name'])
       ->each(function ($user) {
           Inspector::addSpan('user_processing', function () use ($user) {
               // Process user
           });
       });
   

4. Queue Job Monitoring Track job execution time and payload:

   public function handle()
   {
       Inspector::setAttribute('job_payload', $this->payload);
       // Job logic
   }
   

5. Error Tracking Correlate errors with requests:

   try {
       // Risky operation
   } catch (\Exception $e) {
       Inspector::recordException($e);
       throw $e;
   }
   

Laravel-Specific Patterns

• Route Group Tagging Use middleware to tag entire route groups:

  Route::middleware(['tag:api.v1'])->group(function () {
      // Routes here
  });
  

• Service Container Binding Inject Inspector into services:

  public function __construct(private Inspector $inspector) {}
  

• Event Listeners Track async events:

  public function handle(UserRegistered $event)
  {
      $this->inspector->startSpan('user_registration', function () use ($event) {
          // Sync logic
      });
  }
  

Gotchas and Tips

Common Pitfalls

1. Auto-Instrumentation Overhead

   • Disable for local/dev environments:

     'auto_instrument' => env('APP_ENV') !== 'local',
     

   • Exclude specific routes/middleware:

     'ignored_routes' => ['/health', '/debug*'],
     

2. Sampling Rate

   • High sampling may impact performance. Adjust in config:

     'sampling_rate' => 0.1, // 10% of transactions
     

3. Database Query Sampling

   • Disable for high-volume queries:

     'db_sampling_rate' => 0.05,
     

4. Middleware Order

   • Place InspectorApmMiddleware after auth/session middleware to avoid missing metadata.

5. Queue Workers

   • Ensure workers are started with the Laravel environment loaded:

     php artisan queue:work --env=production
     

Debugging Tips

• Check Agent Status

  php artisan inspector:status
  

• Clear Local Cache If config changes aren’t applying:

  php artisan config:clear
  

• Log Level Increase verbosity for troubleshooting:

  'log_level' => \Monolog\Logger::DEBUG,
  

Extension Points

1. Custom Spans Extend with context:

   Inspector::startSpan('payment_processing', function () {
       Inspector::setAttribute('amount', $amount);
       Inspector::setAttribute('currency', $currency);
   });
   

2. Span Events Add sub-events to spans:

   $span = Inspector::startSpan('order_fulfillment');
   $span->addEvent('inventory_check', ['status' => 'success']);
   

3. Resource Tracking Monitor external resources (e.g., HTTP clients):

   $span = Inspector::startSpan('external_api_call');
   try {
       $response = Http::withOptions(['trace' => true])->get('...');
   } finally {
       $span->end();
   }
   

4. Custom Metrics Track business metrics:

   Inspector::incrementMetric('orders.processed');
   Inspector::setMetric('revenue', $amount);
   

5. Error Grouping Group similar errors by type:

   Inspector::recordException($e, ['group' => 'payment_failures']);