Newrelic Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require check24-cp/newrelic-bundle
   

   Enable the bundle in config/bundles.php:

   Check24Cp\NewRelicBundle\NewRelicBundle::class => ['all' => true],
   

2. Basic Configuration Add minimal config to config/packages/check24_cp_newrelic.yaml:

   check24_cp_newrelic:
       license: 'YOUR_NEWRELIC_LICENSE_KEY'
       appname: 'your-app-name'
   

3. First Use Case Immediately start monitoring HTTP requests and CLI commands (e.g., Messenger) with default transaction naming. Verify in New Relic UI under "Transactions" and "Logs".

Implementation Patterns

Core Workflows

1. HTTP Request Monitoring

   • Automatically captures Symfony routes. Use transaction_name_strategy to customize naming:

     check24_cp_newrelic:
         transaction_name_strategy: 'Check24Cp\NewRelicBundle\TransactionNameStrategy\RouteBasedStrategy'
     

   • Exclude routes (e.g., health checks):

     excluded_routes: ['healthcheck', 'api/v1/health']
     

2. CLI/Command Monitoring

   • Wrap Messenger or custom commands with @NewRelic\Transaction:

     use Check24Cp\NewRelicBundle\Attribute\NewRelicTransaction;
     
     #[NewRelicTransaction('my_command')]
     public function __invoke(CommandInterface $command): void
     

3. Log Forwarding

   • Enable log batching for performance:

     logging:
         buffer_size: 50  # Default: 10
         batch_interval: 1000  # Milliseconds
     

   • Link logs to transactions via traceId (auto-injected by the bundle).

4. Exception Handling

   • Exclude specific exceptions (e.g., HttpException):

     excluded_exceptions:
         - Symfony\Component\HttpKernel\Exception\HttpException
     

Integration Tips

• Symfony Events: Hook into kernel.request or messenger.message to customize behavior dynamically.
• Custom Metrics: Use the NewRelic service directly:

  $this->newRelic->recordCustomMetric('custom.metric', 42);
  

• Middleware: Extend existing middleware to add context:

  $this->newRelic->setAttribute('user.id', $user->id);
  

Gotchas and Tips

Pitfalls

1. Configuration Overrides

   • Bundle settings override newrelic.ini values. Set xmit: true in config to force immediate transmission (default: false for batching).
   • Fix: Explicitly configure xmit if relying on newrelic.ini defaults.

2. Transaction Naming Collisions

   • Default strategies may generate duplicate names (e.g., /api/users vs. api.users).
   • Fix: Use RouteBasedStrategy or implement a custom strategy:

     transaction_name_strategy: 'App\Custom\TransactionNameStrategy'
     

3. Log Buffering Delays

   • High buffer_size or slow network may delay log visibility.
   • Fix: Monitor newrelic.log for errors and adjust batch_interval.

4. CLI Transaction Leaks

   • Unclosed transactions in long-running CLI scripts (e.g., cron jobs) can bloat New Relic.
   • Fix: Use #[NewRelicTransaction] with explicit names or wrap in try-finally:

     $this->newRelic->startTransaction('long_running_task');
     try { /* ... */ } finally { $this->newRelic->endTransaction(); }
     

Debugging

• Enable Debug Mode:

  debug: true  # Logs to `var/log/newrelic.log`
  

• Check for Missing License:
  • Errors like NewRelic\Agent::init() failures indicate misconfigured license.
• Transaction Exclusions:
  • Verify excluded_routes/excluded_exceptions are regex-compatible:

    excluded_routes: ['^/api/health.*']  # Regex pattern
    

Extension Points

1. Custom Transaction Name Strategies Implement TransactionNameStrategyInterface:

   class CustomStrategy implements TransactionNameStrategyInterface {
       public function getName(Request $request): string { /* ... */ }
   }
   

   Register in config:

   transaction_name_strategy: 'App\CustomStrategy'
   

2. Log Processor Hooks Extend LogProcessorInterface to modify logs before sending:

   class CustomLogProcessor implements LogProcessorInterface {
       public function process(array $log): array { /* ... */ }
   }
   

   Bind as a service:

   services:
       App\CustomLogProcessor:
           tags: ['check24_cp_newrelic.log_processor']
   

3. Attribute Injection Add custom attributes to transactions dynamically:

   $this->newRelic->setAttribute('custom.key', $value);
   

   Useful for correlating logs/metrics with business context (e.g., user.id).