Snapshot Profiler Newrelic Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aeatech/snapshot-profiler-newrelic
   

2. Register the Service Provider Add to config/app.php under providers:

   Aeatech\SnapshotProfiler\NewRelic\NewRelicSnapshotProfilerServiceProvider::class,
   

3. Publish Configuration

   php artisan vendor:publish --provider="Aeatech\SnapshotProfiler\NewRelic\NewRelicSnapshotProfilerServiceProvider"
   

   This generates config/snapshot-profiler-newrelic.php.

4. Configure New Relic Ensure your newrelic.ini is properly set up with your license key and app name.

5. Enable Profiling Add middleware to app/Http/Kernel.php:

   \Aeatech\SnapshotProfiler\NewRelic\Middleware\NewRelicSnapshotProfiler::class,
   

6. First Use Case Trigger a profiling snapshot via:

   use Aeatech\SnapshotProfiler\NewRelic\Facades\NewRelicSnapshotProfiler;
   
   NewRelicSnapshotProfiler::capture('user_action', ['key' => 'value']);
   

   This will send profiling data to New Relic under the specified transaction name.

Implementation Patterns

Workflow: Production Profiling

1. Instrument Key Routes Use middleware to auto-capture critical paths:

   Route::middleware(['web', 'newrelic.profiler'])->group(function () {
       // High-traffic or slow routes
   });
   

2. Manual Snapshots for Debugging

   // In a controller or service
   NewRelicSnapshotProfiler::capture('checkout_process', [
       'user_id' => auth()->id(),
       'cart_size' => Cart::size(),
   ]);
   

3. Conditional Profiling

   if (app()->environment('production') && request()->wantsJson()) {
       NewRelicSnapshotProfiler::capture('api_endpoint', [
           'response_time' => now()->diffInMilliseconds($startTime),
       ]);
   }
   

4. Integration with Laravel Events

   // In EventServiceProvider
   protected $listen = [
       'order.created' => [
           function ($order) {
               NewRelicSnapshotProfiler::capture('order_created', [
                   'order_id' => $order->id,
                   'amount' => $order->amount,
               ]);
           },
       ],
   ];
   

5. Custom Metrics Combine with New Relic’s custom metrics API:

   NewRelicSnapshotProfiler::addCustomMetric('Database.QueryTime', 150);
   

Gotchas and Tips

Pitfalls

1. New Relic License Requirements

   • Ensure your New Relic account has profiling enabled (not all tiers support it).
   • Verify the newrelic.ini license_key and app_name are correct; otherwise, snapshots won’t appear.

2. Performance Overhead

   • Profiling adds ~5-10% overhead in production. Use sparingly on high-traffic routes.
   • Disable in staging with:

     'enabled' => env('APP_ENV') === 'production',
     

3. Transaction Naming Collisions

   • New Relic truncates transaction names at 255 characters. Use short, descriptive names:

     NewRelicSnapshotProfiler::capture('user_profile_load', [...]); // ✅
     NewRelicSnapshotProfiler::capture('load_user_profile_for_authenticated_user', [...]); // ❌
     

4. Missing Data in Snapshots

   • If custom attributes (e.g., user_id) are missing, ensure they’re serializable (no closures, resources, or circular references).
   • Debug with:

     dd(NewRelicSnapshotProfiler::getLastSnapshotData());
     

5. Middleware Order Matters

   • Place \Aeatech\SnapshotProfiler\NewRelic\Middleware\NewRelicSnapshotProfiler after authentication middleware to include user context:

     'web' => [
         \App\Http\Middleware\Authenticate::class,
         \Aeatech\SnapshotProfiler\NewRelic\Middleware\NewRelicSnapshotProfiler::class,
     ],
     

Tips

1. Filter Noisy Transactions Exclude internal routes from profiling in config:

   'ignore_routes' => [
       'health-check',
       'admin.*',
   ],
   

2. Leverage New Relic Dashboards Create custom dashboards in New Relic to visualize:

   • SnapshotProfiler.TransactionCount (total snapshots per minute).
   • SnapshotProfiler.CustomAttribute.* (e.g., user_id).

3. Batch Snapshots for High Volume Reduce API calls by batching:

   NewRelicSnapshotProfiler::batch(function () {
       NewRelicSnapshotProfiler::capture('bulk_operation', ['items' => 100]);
   });
   

4. Extend with Custom Profiler Implement Aeatech\SnapshotProfiler\Contracts\Profiler to add logic:

   class CustomNewRelicProfiler implements Profiler {
       public function capture(string $name, array $attributes = []): void {
           // Add pre-processing (e.g., sanitize $attributes)
           NewRelicSnapshotProfiler::send($name, $attributes);
       }
   }
   

   Register in config/snapshot-profiler-newrelic.php:

   'profiler' => \App\Services\CustomNewRelicProfiler::class,
   

5. Log Fallbacks If New Relic fails silently, log locally:

   try {
       NewRelicSnapshotProfiler::capture('fallback_test');
   } catch (\Exception $e) {
       \Log::error('NewRelic snapshot failed', ['error' => $e]);
   }