Datadog Bundle Laravel Package

Technical Evaluation

Architecture Fit

• APM Integration: The bundle leverages DataDog’s PHP APM agent to auto-inject session/user metadata (session ID, username) into traces, aligning with modern observability needs for distributed PHP/Laravel apps. This fits well with microservices or monolithic Laravel apps requiring end-to-end tracing.
• ASM Integration: Application Security Monitoring (ASM) for login events (success/failure) is a niche but valuable use case for security-focused apps (e.g., SaaS, fintech). Requires explicit agent configuration (--enable-appsec).
• Symfony Bundle Compatibility: Built as a Symfony bundle, so it integrates seamlessly with Laravel via Symfony’s bridge (e.g., symfony/http-foundation). Assumes Laravel’s session/auth systems are compatible with Symfony’s RequestStack and Security components.

Integration Feasibility

• Low Effort for APM: Minimal setup—just enable the bundle and configure compass_datadog.yaml. APM data flows automatically via the agent.
• ASM Complexity: Requires:
  • Agent-side --enable-appsec flag.
  • Potential customization of login event payloads (e.g., mapping Laravel’s Auth events to ASM-compatible formats).
  • Validation of ASM’s supported event types.
• Laravel-Specific Quirks:
  • Laravel’s session/cookie system must align with Symfony’s RequestStack (likely works out-of-the-box).
  • Custom auth systems (e.g., API tokens) may need adapter layers to inject user context.

Technical Risk

Key Questions

1. Agent Compatibility:
   • Is the DataDog agent already deployed in your environment? If not, what’s the timeline for agent rollout?
   • For ASM, are you using DataDog’s custom rules or default login event detection?
2. Data Privacy:
   • Does your app handle PII (e.g., usernames, session IDs)? Ensure compliance with DataDog’s data retention policies.
3. Customization Needs:
   • Beyond session/username, what additional context (e.g., user roles, request payloads) should be sent to APM/ASM?
4. Testing:
   • How will you validate APM traces and ASM events in CI/CD? (e.g., mock the agent in tests.)
5. Cost:
   • Are you aware of DataDog’s APM/ASM pricing? ASM has usage-based costs for events.

Integration Approach

Stack Fit

• Laravel 8+/Symfony 5+: Ideal fit due to shared dependencies (symfony/http-foundation, symfony/security).
• Agent Requirements:
  • APM: Agent v7+ with PHP APM enabled.
  • ASM: Agent v7.30.0+ with --enable-appsec and AppSec configuration.
• Alternatives Considered:
  • Manual APM: Using ddtrace directly (more control but higher maintenance).
  • Laravel Packages: spatie/laravel-datadog (older, less maintained).

Migration Path

1. Phase 1: APM Only (Low Risk)

   • Install bundle, enable in bundles.php, configure compass_datadog.yaml.
   • Verify traces appear in DataDog with session/username context.
   • Tools: Use DataDog’s APM UI to validate spans.

2. Phase 2: ASM (Medium Risk)

   • Configure agent with --enable-appsec.
   • Extend bundle config to include custom ASM fields (e.g., appsec: { enabled: true, custom_fields: { user_type: "admin" } }).
   • Test login events with DataDog’s Security Signals.
   • Tools: Use DataDog’s AppSec dashboard to monitor events.

3. Phase 3: Customization

   • Extend the bundle to support Laravel-specific auth (e.g., Sanctum, Passport) via event listeners.
   • Example: Listen to Illuminate\Auth\Events\Attempting and inject payloads.

Compatibility

• Laravel-Specific:
  • Session: Uses Symfony’s RequestStack; Laravel’s session should auto-integrate.
  • Auth: Assumes Symfony’s Security component. For Laravel, wrap Auth::user() in a Symfony User object or extend the bundle.
  • Middleware: APM auto-injects; ASM requires login event listeners (e.g., Authenticate middleware).
• Agent-Specific:
  • APM: Works with any PHP app using the agent.
  • ASM: Requires AppSec instrumentation (e.g., dd-trace-php with enable_appsec: true).

Sequencing

1. Prerequisite: Deploy DataDog agent with APM/ASM flags.
2. Bundle Installation: composer require compasshp/datadog-bundle.
3. Configuration:
   • Enable bundle in config/bundles.php.
   • Set compass_datadog.yaml (disable in test).
4. Validation:
   • APM: Trigger a request; verify trace in DataDog.
   • ASM: Test login success/failure; check Security Signals.
5. Customization: Extend bundle for Laravel-specific needs (e.g., auth adapters).

Operational Impact

Maintenance

• Bundle Updates: Monitor compasshp/datadog-bundle for updates (MIT license; low maintenance risk).
• Agent Updates: DataDog agent updates may require bundle version checks (e.g., ASM features).
• Configuration Drift: Centralize compass_datadog.yaml in a config management tool (e.g., Ansible, Laravel Envoy).

Support

• Troubleshooting:
  • APM Issues: Check agent logs (/var/log/datadog/agent.log) and DataDog’s PHP APM docs.
  • ASM Issues: Validate events in DataDog’s AppSec UI and agent config.
• Laravel Debugging:
  • Use ddtrace_php CLI tools to inspect traces: dd-trace run php artisan tinker.
  • For ASM, enable debug logs: compass_datadog: { appsec: { debug: true } }.

Scaling

• Performance:
  • APM: Minimal overhead (~1–5ms per trace). Monitor with DataDog’s APM metrics.
  • ASM: Event volume depends on login frequency. DataDog’s ASM quotas apply.
• High Traffic:
  • APM: Agent auto-scales; no Laravel-side changes needed.
  • ASM: Batch events if login volume spikes (e.g., via queue workers).

Failure Modes