Datadog Bundle Laravel Package

Getting Started

Minimal Steps

1. Install the Bundle Run composer require compasshp/datadog-bundle in your project root.

2. Enable the Bundle Add to config/bundles.php:

   return [
       // ...
       Compass\DatadogBundle\CompassDatadogBundle::class => ['all' => true],
   ];
   

3. Configure Basic Settings Create config/packages/compass_datadog.yaml with minimal APM/ASM settings:

   compass_datadog:
       tracing:
           enabled: true
       appsec:
           enabled: true
   

4. Verify Agent Setup Ensure the DataDog Agent is running with tracing (--enable-appsec if using ASM).

5. First Use Case Trigger a request (e.g., login/logout or API call). Check DataDog APM/ASM dashboards for:

   • Session ID in APM traces.
   • Login attempts in ASM events.

Implementation Patterns

Core Workflows

1. APM Integration

   • Automatic Context Injection: The bundle auto-injects session_id and user (if logged in) into DataDog traces.
   • Custom Properties: Extend trace context via config:

     compass_datadog:
         tracing:
             custom_properties:
                 - 'user.role'
                 - 'request.ip'
     

   • Middleware Hooks: Use compass_datadog.trace event to modify traces dynamically:

     // In EventSubscriber
     public function onTrace(ContextEvent $event) {
         $event->getTrace()->setTag('custom.tag', 'value');
     }
     

2. ASM Integration

   • Login Event Tracking: Auto-captures success/failure login attempts (via AuthenticatesUsers trait or custom guards).
   • Custom ASM Properties: Add metadata to ASM events:

     compass_datadog:
         appsec:
             custom_properties:
                 - 'user.plan'
     

   • Event Filtering: Disable for specific routes:

     compass_datadog:
         appsec:
             ignore_routes:
                 - '/admin/*'
     

3. Conditional Tracing

   • Disable in non-production environments:

     when@!*prod:
         compass_datadog:
             tracing:
                 enabled: false
     

Integration Tips

• Laravel Auth: Works seamlessly with Laravel’s built-in auth (e.g., auth()->user()).
• Custom Guards: Extend Compass\DatadogBundle\Security\Authenticator to support custom guards.
• Queue Workers: For async tasks, manually trigger traces:

  use Compass\DatadogBundle\Tracing\Tracer;
  $tracer = app(Tracer::class);
  $tracer->startTrace('job.processing');
  

Gotchas and Tips

Pitfalls

1. Agent Misconfiguration

   • Symptom: No traces/events in DataDog.
   • Fix: Verify agent is running with:

     datadog-agent status
     

     For ASM, ensure --enable-appsec is set.

2. Session ID Missing

   • Cause: Session not started before trace initiation.
   • Fix: Ensure middleware (e.g., StartSession) runs before compass_datadog.trace.

3. ASM Events Not Triggering

   • Cause: Login logic bypasses Laravel’s auth system (e.g., custom auth).
   • Fix: Manually dispatch compass_datadog.appsec.login event:

     event(new LoginEvent($user, $success));
     

4. Performance Overhead

   • Symptom: Slower requests in production.
   • Fix: Disable in staging/dev:

     when@prod:
         compass_datadog:
             tracing:
                 enabled: true
     

Debugging

• Check Trace Context: Use dd(app('compass_datadog.trace_context')->all()) to inspect injected data.
• Log Events: Enable debug logging in config/logging.php to see bundle events:

  'channels' => [
      'compass_datadog' => [
          'driver' => 'single',
          'path' => storage_path('logs/compass_datadog.log'),
          'level' => 'debug',
      ],
  ],
  

Extension Points

1. Custom Tracers Override the default tracer by binding a service:

   $this->app->bind(Tracer::class, function () {
       return new CustomTracer();
   });
   

2. Event Subscribers Listen to compass_datadog.trace or compass_datadog.appsec.login events for custom logic.

3. Configuration Overrides Dynamically adjust settings via environment variables:

   compass_datadog:
       tracing:
           enabled: '%env(bool:DATADOG_TRACING_ENABLED,false)%'
   

Pro Tips

• Tagging Strategies: Use custom_properties to tag traces by user segments (e.g., user.tier).
• ASM Rules: Leverage DataDog’s ASM rules to correlate events with traces.
• Sampling: Configure DataDog’s sampling rules to reduce overhead.