Elastic Apm Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require chq81/elastic-apm-bundle
   

   For Symfony Flex projects, this auto-configures the bundle.

2. Configuration: Create config/packages/elastic_apm.yaml with minimal required settings:

   elastic_apm:
       server_url: 'http://localhost:8200'  # Default Elastic APM Server URL
       service_name: 'your-app-name'       # Your Symfony app's name
       secret_token: 'your-secret-token'   # Required for APM Server auth
   

3. First Use Case:

   • Deploy the app and verify transactions appear in Kibana APM under your service name.
   • Check the Symfony logs (var/log/dev.log) for APM initialization errors.

Implementation Patterns

Core Workflows

1. Automatic Transaction Capture:

   • The bundle auto-instruments Symfony’s HTTP kernel, capturing:
     • HTTP requests (status, duration, response size).
     • Exceptions (stack traces, error groups).
     • Database queries (via Doctrine integration).
   • Example: No manual code changes needed for basic APM monitoring.

2. Custom Transactions:

   use Chq81\ElasticApmBundle\ElasticApm;
   
   public function customAction(ElasticApm $apm)
   {
       $transaction = $apm->startTransaction('custom_transaction_name');
       try {
           // Business logic here
           $apm->captureMessage('Processing started');
       } finally {
           $transaction->end();
       }
   }
   

3. Contextual Data:

   • Attach metadata to transactions:

   $transaction->setContext('user', ['id' => 123, 'role' => 'admin']);
   $transaction->setLabel('priority', 'high');
   

4. Error Tracking:

   • Exceptions are automatically captured. For manual errors:

   $apm->captureError(new \RuntimeException('Manual error'), [
       'custom_field' => 'value',
   ]);
   

Integration Tips

• Doctrine DBAL: Enable via config:

  elastic_apm:
      db:
          enabled: true
  

  Captures SQL queries, durations, and bind parameters.

• Monolog Integration:

  elastic_apm:
      monolog:
          enabled: true
          level: error  # Logs errors to APM
  

• Environment-Specific Config: Use Symfony’s %kernel.environment% to toggle APM in dev vs. prod:

  elastic_apm:
      enabled: '%kernel.debug% ? false : true%'  # Disable in dev
  

Gotchas and Tips

Pitfalls

1. Secret Token Leaks:

   • Risk: Hardcoding secret_token in elastic_apm.yaml exposes it in version control.
   • Fix: Use Symfony’s parameter_bag or environment variables:

     elastic_apm:
         secret_token: '%env(APM_SECRET_TOKEN)%'
     

2. Performance Overhead:

   • Issue: APM adds ~5–10ms latency per request. Disable in dev:

     elastic_apm:
         enabled: false  # For local/dev environments
     

3. Doctrine Integration Conflicts:

   • Problem: If using multiple Doctrine connections, only the default connection is monitored by default.
   • Fix: Configure specific connections:

     elastic_apm:
         db:
             connections:
                 - 'default'
                 - 'read_replica'
     

4. Transaction Naming:

   • Gotcha: Custom transaction names must be unique per request to avoid APM UI clutter.
   • Tip: Use dynamic names (e.g., user_${id}_profile).

Debugging

• Logs: Check var/log/dev.log for APM initialization errors (e.g., invalid server_url).
• APM Server Logs: Verify the agent is connecting to the APM Server:

  curl -v http://localhost:8200
  

• Disabled Transactions: If transactions don’t appear, ensure:
  • The service_name is correct in Kibana.
  • The APM Server is running and accessible.

Extension Points

1. Custom Spans:

   • Extend the agent for framework-specific spans (e.g., Symfony Messenger):

   $span = $apm->startSpan('messenger_handle');
   $span->end();
   

2. Middleware Integration:

   • Use the ElasticApmEvent subscriber to hook into Symfony events:

   use Chq81\ElasticApmBundle\Event\ElasticApmEvent;
   
   public function onKernelRequest(ElasticApmEvent $event)
   {
       $event->getTransaction()->setLabel('custom', 'value');
   }
   

3. Agent Configuration:

   • Pass additional APM agent options via config:

   elastic_apm:
       agent:
           capture_body: 'all'  # Log request/response bodies
           ignore_urls: ['/health']  # Exclude URLs
   

4. Async Processing:

   • For long-running tasks (e.g., cron jobs), manually manage transactions:

   $apm->startTransaction('cron_job');
   try {
       // Long task...
   } finally {
       $apm->getCurrentTransaction()->end();
   }