Newrelic Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require temando/newrelic-bundle
   

   (Note: The composer.json lists temando/newrelic-bundle, but the README references ekino/newrelic-bundle. Use the correct namespace for your project.)

2. Enable the Bundle Add to AppKernel.php:

   new Temando\Bundle\NewRelicBundle\TemandoNewRelicBundle(),
   

3. Configure Basic Settings

   # app/config/config.yml
   ekino_new_relic:
       enabled: true
       license_key: "YOUR_NEW_RELIC_LICENSE_KEY"  # Required
       application_name: "YourAppName"
   

4. First Use Case Deploy and check New Relic dashboard to verify transactions (e.g., routes, CLI commands) are being recorded.

Implementation Patterns

Core Workflows

1. Transaction Naming

   • Route-based: Default (transaction_naming: route) names transactions after Symfony routes (e.g., homepage).
   • Controller-based: Use transaction_naming: controller for controller class names (e.g., AppBundle:Post:show).
   • Custom Strategy: Implement TransactionNamingStrategyInterface for bespoke logic (e.g., naming by user action):

     transaction_naming: service
     transaction_naming_service: app.newrelic.transaction_namer
     

     // src/AppBundle/Service/NewRelicTransactionNamer.php
     class NewRelicTransactionNamer implements TransactionNamingStrategyInterface
     {
         public function getTransactionName(Request $request) {
             return $request->get('action', 'default_transaction');
         }
     }
     

2. Ignoring Transactions

   • Exclude routes, paths, or CLI commands from monitoring:

     ignored_routes: [admin_dashboard]
     ignored_paths: [^/api/health]
     ignored_commands: [app:cache:warmup]
     

3. CLI Command Monitoring Enable with log_commands: true to track background jobs (e.g., cron tasks):

   php bin/console app:send-email
   

   (Transaction name = command name.)

4. Deployment Notifications Automate via Capifony or manually:

   php bin/console newrelic:notify-deployment --revision="abc123" --description="Hotfix for login bug"
   

Integration Tips

1. Symfony Cache Enable using_symfony_cache: true to split ESI transactions (improves granularity):

   using_symfony_cache: true
   

2. RUM Instrumentation

   • Disable for specific requests (e.g., HTML editors) via URL param:

     /editor?_instrument=false
     

   • Configure in config.yml:

     instrument: true
     

3. Exception Logging Enable to send errors to New Relic:

   log_exceptions: true
   

4. Debugging Use logging: true to log New Relic interactions to Symfony’s log (e.g., app/log/dev.log).

Gotchas and Tips

Pitfalls

1. License Key Required

   • Without license_key, the bundle logs warnings but won’t send data to New Relic.
   • Fix: Set license_key in config.yml or environment variables.

2. Transaction Naming Conflicts

   • Route-based naming may clash if routes share names (e.g., home for / and /home).
   • Fix: Use controller or a custom strategy for disambiguation.

3. CLI Command Delays

   • Commands may not appear in New Relic immediately due to background processing.
   • Fix: Wait 5–10 minutes or check "Background Jobs" in the New Relic UI.

4. Symfony Cache Overhead

   • using_symfony_cache: true adds minor performance cost but improves accuracy.
   • Tip: Test in staging before enabling in production.

5. RUM Instrumentation Side Effects

   • Disabling RUM (instrument: false) removes all browser monitoring.
   • Tip: Use selectively via _instrument param for dynamic control.

Debugging Tips

1. Check Logs Enable logging: true to debug New Relic interactions:

   logging: true
   

   (Logs appear in app/log/dev.log or prod.log.)

2. Verify Transactions

   • Use newrelic_set_transaction_name() manually in controllers for edge cases:

     use NewRelic\Agent;
     Agent::setTransactionName('CustomTransaction');
     

3. API Key Permissions

   • Ensure the api_key (for deployment notifications) has "Deploy notifications" permissions in New Relic.

4. Environment-Specific Config Override settings per environment (e.g., config_dev.yml):

   # app/config/config_dev.yml
   ekino_new_relic:
       logging: true
       ignored_routes: [admin_dashboard_dev]
   

Extension Points

1. Custom Transaction Naming Extend the bundle by implementing TransactionNamingStrategyInterface:

   namespace AppBundle\Service;
   use Ekino\Bundle\NewRelicBundle\TransactionNamingStrategy\TransactionNamingStrategyInterface;
   use Symfony\Component\HttpFoundation\Request;
   
   class CustomNamer implements TransactionNamingStrategyInterface
   {
       public function getTransactionName(Request $request) {
           return 'Custom:' . $request->get('_route');
       }
   }
   

   Register as a service:

   services:
       app.newrelic.transaction_namer:
           class: AppBundle\Service\CustomNamer
           tags:
               - { name: ekino_new_relic.transaction_naming_strategy }
   

2. Event Listeners Hook into New Relic events (e.g., newrelic.transaction):

   use Ekino\Bundle\NewRelicBundle\Event\NewRelicEvents;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class NewRelicSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               NewRelicEvents::TRANSACTION => 'onTransaction',
           ];
       }
   
       public function onTransaction(NewRelicTransactionEvent $event)
       {
           // Modify transaction name/data
       }
   }
   

3. Sonata Admin/Block Integration

   • For SonataAdmin, ensure the block is enabled in sonata_admin config:

     sonata_admin:
         dashboard:
             blocks:
                 - { type: ekino.newrelic.block.simple, position: right }
     

   • Use Twig to render blocks dynamically:

     {{ sonata_block_render({ 'type': 'ekino.newrelic.block.simple' }, {
         'reference': 'YOUR_NEW_RELIC_APP_ID'
     }) }}