Newrelic Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require c24-toys/newrelic-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       C24Toys\NewRelicBundle\NewRelicBundle::class => ['all' => true],
   ];
   

2. Configuration: Publish the default config:

   php bin/console config:dump-reference c24_toys_newrelic
   

   Update config/packages/c24_toys_newrelic.yaml with your New Relic license key:

   c24_toys_newrelic:
       license_key: 'YOUR_NEW_RELIC_LICENSE_KEY'
       transaction_name: 'default'  # or 'route', 'controller', or custom
   

3. First Use Case:

   • Route Naming: Ensure transactions auto-name via routes (default). Test by accessing a route and checking New Relic’s UI for the transaction name.
   • Console Commands: Run a command (e.g., php bin/console cache:clear) and verify the transaction name matches the command in New Relic.

Implementation Patterns

Core Workflows

1. Transaction Naming Strategies:

   • Route-Based: Default. Use transaction_name: route in config.
   • Controller-Based: Use transaction_name: controller to name transactions after controller classes (e.g., App\Controller\HomeController).
   • Custom Strategy: Implement C24Toys\NewRelicBundle\TransactionNamingStrategyInterface and bind it via dependency injection:

     services:
         App\Service\CustomTransactionNamer:
             tags: ['c24_toys_newrelic.transaction_naming_strategy']
     

2. Middleware Integration:

   • The bundle auto-injects New Relic middleware for HTTP requests. Extend it by creating a custom subscriber:

     use Symfony\Component\HttpKernel\Event\RequestEvent;
     use C24Toys\NewRelicBundle\Event\NewRelicEvents;
     
     public function onKernelRequest(RequestEvent $event) {
         $transaction = \NewRelic::getTransaction();
         $transaction->setCustomAttribute('custom_key', 'value');
     }
     

     Register the subscriber in services.yaml:

     tags: ['kernel.event_subscriber']
     

3. Console Command Enhancements:

   • Transactions auto-name to the command name. Add custom attributes:

     use C24Toys\NewRelicBundle\NewRelic\Console\CommandTrait;
     
     class MyCommand extends Command {
         use CommandTrait;
     
         protected function execute(InputInterface $input, OutputInterface $output) {
             $this->setNewRelicAttribute('command_type', 'custom');
             // ...
         }
     }
     

4. Database and External Calls:

   • Use New Relic’s API to instrument queries or HTTP calls:

     \NewRelic\Agent::getTransaction()->addCustomParameter('db_query', 'SELECT * FROM users');
     

Integration Tips

• Symfony Events: Leverage NewRelicEvents::TRANSACTION or NewRelicEvents::ERROR to hook into transaction lifecycle or errors.
• Monolog Integration: Forward Monolog logs to New Relic:

  monolog:
      handlers:
          newrelic:
              type: service
              id: c24_toys_newrelic.handler.newrelic
  

• Environment-Specific Config: Use %kernel.environment% to toggle New Relic in dev/staging:

  c24_toys_newrelic:
      enabled: '%env(bool:NEW_RELIC_ENABLED)%'
  

Gotchas and Tips

Pitfalls

1. License Key Sensitivity:

   • Hardcoding the license key in config/packages/ exposes it. Use environment variables:

     license_key: '%env(NEW_RELIC_LICENSE_KEY)%'
     

   • Debugging: If transactions don’t appear, verify the key is correct and the bundle is loaded (check php bin/console debug:config c24_toys_newrelic).

2. Transaction Naming Conflicts:

   • Custom strategies may override default naming. Test edge cases (e.g., anonymous routes, CLI commands) to avoid mislabeled transactions.

3. Performance Overhead:

   • New Relic adds latency. Disable in development:

     c24_toys_newrelic:
         enabled: false  # Set to true in production
     

4. Console Command Transactions:

   • Long-running commands may hit New Relic’s transaction timeout (default: 5 minutes). Use ignore_user_abort(true) or split into smaller commands.

Debugging

• Transaction Drops: If transactions disappear, check:
  • The newrelic.ini file (if manually configured) isn’t conflicting with the bundle.
  • The Symfony profiler for errors during kernel boot.
• Custom Attributes: Use \NewRelic\Agent::getTransaction()->getName() to debug transaction names dynamically.

Extension Points

1. Custom Metrics:

   • Add custom metrics via the New Relic API:

     \NewRelic\Agent::recordCustomMetric('Custom/Category', 42);
     

   • Bind a service to c24_toys_newrelic.metric_recorder to centralize metric recording.

2. Error Handling:

   • Extend error reporting by subscribing to NewRelicEvents::ERROR:

     public function onNewRelicError(NewRelicErrorEvent $event) {
         $event->getError()->setCustomAttribute('user_id', $this->getUserId());
     }
     

3. Async Processing:

   • For background jobs (e.g., Symfony Messenger), manually start/end transactions:

     \NewRelic\Agent::getApplication()->startTransaction('BackgroundJob', 'Job/ProcessOrder');
     try {
         // Job logic
     } finally {
         \NewRelic\Agent::getApplication()->endTransaction();
     }
     

Config Quirks

• Transaction Timeout: Adjust via newrelic.ini (not the bundle):

  transaction_tracer.transaction_threshold = 0.5
  

• Ignored URLs: Exclude paths from monitoring:

  c24_toys_newrelic:
      ignored_urls:
          - '^/api/doc'
          - '^/webhook/'