Elastic Apm Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require divlooper/elastic-apm-bundle
   

   Add to bundles.php:

   DivLooper\ElasticAPMBundle\DivLooperElasticAPMBundle::class => ['all' => true],
   

2. Basic Configuration (config/packages/div_looper_elastic_apm.yaml):

   div_looper_elastic_apm:
       app_name: 'MyApp'
       app_version: '1.0'
       elastic_apm_server: 'http://localhost:8200'
       secret_token: 'your-secret-token'  # Required for APM server auth
   

3. First Use Case:

   • The bundle auto-instruments Symfony’s HTTP kernel. No manual code changes are needed for basic request/response tracking.
   • Verify APM server receives data by checking Elastic APM UI or logs.

Implementation Patterns

Core Workflows

1. Auto-Instrumentation:

   • Captures HTTP requests/responses, exceptions, and performance metrics (e.g., DB queries, HTTP clients) out-of-the-box.
   • Works with Symfony’s HttpFoundation and HttpClient components.

2. Manual Transaction Spans:

   • Use the ElasticAPM service to manually start/end spans (e.g., for business logic):

     $transaction = $this->get('elastic_apm')->startTransaction('custom_operation');
     try {
         // Business logic here
         $transaction->end();
     } catch (\Exception $e) {
         $transaction->captureException($e);
         $transaction->end();
     }
     

3. Custom Context Data:

   • Attach metadata to transactions/spans:

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

4. Error Tracking:

   • Exceptions are automatically captured and sent to APM. For custom errors:

     $this->get('elastic_apm')->captureError(new \RuntimeException('Custom error'), [
         'custom_field' => 'value'
     ]);
     

Integration Tips

• Database Queries: Use doctrine.dbal.connection events to track SQL queries:

  # config/packages/div_looper_elastic_apm.yaml
  div_looper_elastic_apm:
      db_instrumentation: true
  

• HTTP Clients: Works with Symfony’s HttpClient and Guzzle. For Guzzle, ensure the bundle’s middleware is added:

  $client = new \GuzzleHttp\Client([
      'handler' => \DivLooper\ElasticAPMBundle\Handler\APMHandler::create()
  ]);
  

• Async Jobs: Use the ElasticAPM service in background workers (e.g., Symfony Messenger) to track job execution.

Gotchas and Tips

Pitfalls

1. Secret Token:

   • Mandatory: The secret_token must match the APM server’s configuration. Omitting or misconfiguring it silently disables APM.
   • Security: Never hardcode tokens in version-controlled files. Use environment variables or Symfony’s parameter_bag.

2. Performance Overhead:

   • APM adds ~5-15ms latency per request. Disable in staging/production if unused:

     div_looper_elastic_apm:
         enabled: '%env(bool:ELASTIC_APM_ENABLED)%'
     

3. Deprecated Features:

   • The package is unmaintained (last release: 2019). Some Elastic APM server versions may require manual adjustments (e.g., payload format).

4. Database Instrumentation:

   • Only works with Doctrine DBAL. For other DBALs (e.g., PDO), manually instrument queries using the ElasticAPM service.

Debugging

• Enable Debug Mode:

  div_looper_elastic_apm:
      debug: true
  

  Logs APM events to Symfony’s dev.log.

• Validate Payloads: Use Elastic APM’s server logs or tools like APM Agent’s curl test to verify data format.

• Common Issues:

  • No Data in APM: Check secret_token, network connectivity, and Symfony’s monolog logs.
  • 500 Errors: Ensure the APM server URL is correct and accessible from the Symfony app.

Extension Points

1. Custom Payloads: Override the bundle’s APMClient to modify payloads before sending:

   // src/Service/APMClient.php
   class CustomAPMClient extends \DivLooper\ElasticAPMBundle\Client\APMClient {
       public function sendEvent($event) {
           $event['custom_field'] = 'value';
           parent::sendEvent($event);
       }
   }
   

   Bind it in services.yaml:

   services:
       DivLooper\ElasticAPMBundle\Client\APMClient: '@App\Service\CustomAPMClient'
   

2. Event Listeners: Subscribe to elastic_apm.transaction or elastic_apm.error events to enrich data:

   // src/EventListener/APMListener.php
   class APMListener implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               'elastic_apm.transaction' => 'onTransaction',
           ];
       }
   
       public function onTransaction(TransactionEvent $event) {
           $event->getTransaction()->setContext('custom', ['data' => 'value']);
       }
   }
   

3. Environment-Specific Config: Use Symfony’s %kernel.environment% to toggle APM in dev/staging:

   div_looper_elastic_apm:
       enabled: '%kernel.debug%'