Apm Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require berriart/apm-bundle
   

   Add to config/bundles.php:

   Berriart\APMBundle\BerriartAPMBundle::class => ['all' => true],
   

2. Configuration: Enable Application Insights (or future APM) in config/packages/berriart_apm.yaml:

   berriart_apm:
       apms:
           application_insights:
               enabled: true
               instrumentation_key: "%env(APP_INSIGHTS_INSTRUMENTATION_KEY)%"
   

3. First Use Case: Deploy and verify telemetry in your APM dashboard (e.g., Azure Portal for Application Insights). Check for tracked requests, exceptions, and system metrics.

Implementation Patterns

Core Workflows

1. Automatic Instrumentation:

   • Requests: All HTTP requests are auto-tracked (status, duration, memory, route/controller).
   • Exceptions: Symfony exceptions are captured and sent to APM.
   • Commands: Console commands log execution details (duration, args, memory).

2. Manual Telemetry: Use the APMClient service to send custom events:

   $this->container->get('berriart_apm.client')->trackEvent('custom_event', ['key' => 'value']);
   

3. Deployment Notifications: Trigger via CLI:

   php bin/console berriart:apm:send-message --message="Deployment started" --type=info
   

Integration Tips

• Environment-Specific Config: Override berriart_apm.yaml per environment (e.g., berriart_apm_test.yaml).
• Sampling: Disable for local/dev (set sampling_rate: 0 in config) to reduce noise.
• Middleware Hooks: Extend request tracking by implementing Berriart\APMBundle\EventListener\RequestListenerInterface.

Gotchas and Tips

Pitfalls

1. Beta API Instability:

   • Avoid relying on undocumented methods; check changelog for breaking changes.
   • Test in staging before production.

2. Performance Overhead:

   • APM telemetry adds ~5–10ms per request. Monitor impact in high-throughput apps.
   • Disable in CI/CD pipelines if not needed.

3. Configuration Quirks:

   • Instrumentation Key: Must be set in .env (e.g., APP_INSIGHTS_INSTRUMENTATION_KEY).
   • Multi-APM: Only Application Insights is functional; New Relic is "coming soon" (unmaintained).

4. Debugging:

   • Enable debug mode in config:

     berriart_apm:
         debug: true
     

   • Logs appear in var/log/dev.log (Symfony default).

Extension Points

1. Custom Metrics: Extend Berriart\APMBundle\Service\APMClient to add custom telemetry:

   $client->trackCustomMetric('db.query.time', $durationMs);
   

2. Event Listeners: Subscribe to berriart.apm.event for pre/post-processing:

   // src/EventListener/CustomAPMListener.php
   public function onAPMEvent(APMEvent $event) {
       $event->addContext(['custom_key' => 'value']);
   }
   

3. APM Service Plugins: Implement Berriart\APMBundle\Service\APMInterface to add new APM backends (e.g., Datadog).

Maintenance Notes

• Archived Status: No updates expected. Fork or migrate to alternatives like:
  • symfony-monolog-apm (for Monolog integration).
  • snuffleupagus/snuffleupagus (for PHP profiling).