Web Snapshot Profiler Newrelic Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require aeatech/web-snapshot-profiler-newrelic-bundle
   

   Enable the bundle in config/bundles.php:

   AEATech\WebSnapshotProfilerNewrelicBundle\AEATechWebSnapshotProfilerNewrelicBundle::class => ['dev' => true, 'prod' => true],
   

2. Configure Environment Variables: Add to .env:

   AEA_TECH_WEB_SNAPSHOT_PROFILER_NEWRELIC_APP_NAME="YourAppName"
   AEA_TECH_WEB_SNAPSHOT_PROFILER_NEWRELIC_LICENSE="your_newrelic_license_key"
   

3. Enable Profiling: Update config/packages/aea_tech_web_snapshot_profiler_newrelic.yaml:

   aea_tech_web_snapshot_profiler_newrelic:
       is_profiling_enabled: true
   

4. First Use Case: Trigger a snapshot for a specific route or controller method:

   use AEATech\WebSnapshotProfilerNewrelicBundle\Attribute\Snapshot;
   
   #[Snapshot]
   public function criticalAction(Request $request): Response
   {
       // Your logic here
   }
   

Implementation Patterns

Common Workflows

1. Route-Level Profiling: Use the Snapshot attribute on route controllers or methods to profile specific endpoints:

   #[Route('/profile-me', name: 'profile_me')]
   #[Snapshot]
   public function profileMe(): Response
   {
       return new Response('Profiling this endpoint!');
   }
   

2. Conditional Profiling: Dynamically enable/disable profiling based on environment or user roles:

   # config/packages/aea_tech_web_snapshot_profiler_newrelic.yaml
   aea_tech_web_snapshot_profiler_newrelic:
       is_profiling_enabled: '%kernel.debug%'  # Only in debug mode
   

3. Custom Events: Manually trigger snapshots for non-HTTP logic (e.g., CLI commands or background jobs):

   use AEATech\WebSnapshotProfilerNewrelicBundle\Service\SnapshotProfiler;
   
   public function __construct(private SnapshotProfiler $profiler) {}
   
   public function processData()
   {
       $this->profiler->startSnapshot('data_processing');
       // Your logic here
       $this->profiler->endSnapshot();
   }
   

4. Integration with Symfony Events: Listen to kernel events to profile specific requests:

   use Symfony\Component\HttpKernel\Event\RequestEvent;
   use AEATech\WebSnapshotProfilerNewrelicBundle\Service\SnapshotProfiler;
   
   public function onKernelRequest(RequestEvent $event, SnapshotProfiler $profiler)
   {
       if ($event->getRequest()->getPathInfo() === '/admin') {
           $profiler->startSnapshot('admin_dashboard');
       }
   }
   

5. New Relic Custom Attributes: Add custom attributes to enrich profiling data:

   $this->profiler->addAttribute('user_id', $user->id);
   $this->profiler->addAttribute('request_source', $request->headers->get('X-Request-Source'));
   

Gotchas and Tips

Pitfalls

1. New Relic Extension Dependency:

   • Ensure ext-newrelic (v12.1+) is installed and enabled. Verify with:

     php -m | grep newrelic
     

   • If missing, install via PECL:

     pecl install newrelic
     

2. Profiling Overhead:

   • Profiling adds latency. Disable in prod unless explicitly needed:

     aea_tech_web_snapshot_profiler_newrelic:
         is_profiling_enabled: false  # Default for prod
     

   • Use is_profiling_enabled conditionally (e.g., only for admin users or specific routes).

3. Attribute Conflicts:

   • The #[Snapshot] attribute may conflict with other attributes on the same method. Ensure it’s the last attribute in the list:

     #[Route('/example')]
     #[ApiPlatform\Operation(...)]
     #[Snapshot]  // Last attribute
     

4. Environment Variable Sensitivity:

   • The license key is exposed in bundles.php if not properly masked. Use %env() in config/packages/ to avoid hardcoding:

     newrelic:
         license: '%env(string:NEW_RELIC_LICENSE)%'
     

5. New Relic App Name Clashes:

   • If multiple apps use the same app_name, snapshots may merge incorrectly. Append a unique suffix (e.g., app_name: "MyApp-Staging").

Debugging

1. Check Profiler Status: Verify profiling is enabled via Symfony’s debug toolbar or logs:

   bin/console debug:config aea_tech_web_snapshot_profiler_newrelic
   

2. New Relic UI:

   • Navigate to Transactions > Snapshot Profiler in New Relic to view snapshots.
   • Filter by aea_tech_web_snapshot_profiler custom attribute.

3. Log Errors: Enable debug logging in config/packages/monolog.yaml:

   handlers:
       main:
           type: stream
           path: "%kernel.logs_dir%/%kernel.environment%.log"
           level: debug
           channels: ["!event"]
   

4. Snapshot Not Appearing?:

   • Ensure the #[Snapshot] attribute is on a public method.
   • Check for PHP errors in the profiled code (unhandled exceptions may abort profiling).

Extension Points

1. Custom Snapshot Events: Extend the profiler to support custom events (e.g., database queries, external API calls):

   // src/Service/CustomProfiler.php
   use AEATech\WebSnapshotProfilerNewrelicBundle\Service\SnapshotProfiler;
   
   class CustomProfiler
   {
       public function __construct(private SnapshotProfiler $profiler) {}
   
       public function profileQuery(string $query): void
       {
           $this->profiler->startSnapshot('database_query', ['query' => $query]);
           // Execute query
           $this->profiler->endSnapshot();
       }
   }
   

2. Override Default Configuration: Create a custom bundle to modify the profiler’s behavior:

   // src/DependencyInjection/AEATechWebSnapshotProfilerNewrelicExtension.php
   public function load(array $configs, ContainerBuilder $container)
   {
       $configuration = new Configuration();
       $config = $this->processConfiguration($configuration, $configs);
   
       $container->setParameter('aea_tech_web_snapshot_profiler_newrelic.custom_attr', $config['custom_attribute']);
   }
   

3. New Relic API Integration: Use the New Relic API to programmatically fetch or analyze snapshots:

   use NewRelic\Agent;
   
   public function analyzeSnapshots()
   {
       $snapshots = Agent::getTransactionSnapshots();
       // Process snapshots
   }
   

4. Symfony Flex Recipes: Create a custom recipe to automate installation for your team:

   # resources/recipes/AEATechWebSnapshotProfilerNewrelicBundle.yaml
   name: "AEATech Web Snapshot Profiler New Relic Bundle"
   recipe:
       type: "symfony/bundle"
       config:
           bundles:
               AEATech\WebSnapshotProfilerNewrelicBundle\AEATechWebSnapshotProfilerNewrelicBundle: ["dev" => true, "prod" => true]