Correlation Bundle Laravel Package

Product Decisions This Supports

• Distributed Tracing Lightweight Alternative: Enables correlation ID propagation across microservices, APIs, and async workflows (Messenger) without adopting a full APM (e.g., Datadog, New Relic). Reduces debugging friction for cross-service requests by stitching logs/messages with a single identifier.
• Observability Roadmap: Foundational layer for future tracing/telemetry integrations (e.g., OpenTelemetry). Avoids vendor lock-in while standardizing ID generation/propagation.
• Build vs. Buy: Justifies not building a custom solution for correlation IDs, given the package’s battle-tested abstractions (e.g., ResetInterface for worker safety) and Symfony-native design.
• Use Cases:
  • API Gateways: Propagate IDs through HTTP clients to downstream services.
  • Async Workflows: Correlate Messenger messages to their originating HTTP requests.
  • Logging: Enrich Monolog entries for centralized log analysis (e.g., ELK).
  • Real-Time Updates: Tag Mercure hub events with IDs for debugging.
  • CLI/Console: Assign IDs to long-running commands for auditability.

When to Consider This Package

• Adopt if:

  • Your stack uses Symfony 6.4+ and PHP 8.2+.
  • You need lightweight correlation IDs (not full distributed tracing) with minimal overhead.
  • Your system includes HTTP APIs, async messaging (Messenger), or CLI tools that require ID propagation.
  • You’re already using Monolog, Mercure, or HTTP Client and want seamless integration.
  • You prioritize worker-mode safety (e.g., FrankenPHP, Messenger workers).

• Look elsewhere if:

  • You need W3C Trace Context compliance (use Hex32CorrelationIdGenerator + custom headers).
  • Your stack is non-Symfony (e.g., Laravel, Node.js).
  • You require sampling/rate-limiting for correlation IDs (this is a basic propagation tool).
  • You’re already using a dedicated APM with built-in correlation (e.g., OpenTelemetry SDK).
  • You need performance-critical ID generation (this adds ~1ms latency per request).

How to Pitch It (Stakeholders)

For Executives: "This package lets us add distributed tracing without the complexity or cost of a full APM. By automatically stitching together logs, HTTP calls, and async messages with a single correlation ID, we’ll slash debugging time for cross-service issues—critical for scaling our API and microservices. It’s a 2-hour install with zero runtime overhead, and it plays nicely with our existing Symfony stack."

For Engineering: *"Aubes’ Correlation Bundle gives us:

• Zero-config correlation IDs for HTTP, CLI, and Messenger (auto-generated or header-propagated).
• Worker-safe storage (resets per request/message, safe for FrankenPHP/Messenger).
• Extensible generators (UUIDv7 for timestamps, Hex32 for W3C compliance).
• Seamless integrations with Monolog (log enrichment), Mercure (real-time events), and HTTP Client (downstream calls). No APM vendor lock-in; just plug-and-play observability. Let’s scope this for our next API release and CLI tools—it’s a no-brainer for observability debt reduction."