Opentracing Bundle Guzzle Laravel Package

Product Decisions This Supports

• Distributed Tracing for Microservices: Enables seamless integration of OpenTracing (now OpenTelemetry) into Symfony applications using Guzzle HTTP clients, allowing end-to-end request tracing across services. Critical for debugging latency, errors, and dependencies in microservices architectures.
• Observability Roadmap: Aligns with broader observability initiatives (e.g., APM, logging, metrics) by providing standardized tracing headers for external HTTP calls. Reduces manual instrumentation effort for engineering teams.
• Build vs. Buy: Buy—avoids reinventing distributed tracing middleware for Guzzle. The package is lightweight, battle-tested (used internally at Auxmoney), and integrates with the mature OpentracingBundle-core.
• Use Cases:
  • API Gateways: Trace requests flowing through Symfony-based gateways to downstream services.
  • Background Jobs: Instrument Guzzle calls in Symfony Messenger or cron jobs (e.g., payment processing, notifications).
  • Legacy System Modernization: Add observability to older Symfony apps without major refactoring.
  • Third-Party Integrations: Monitor calls to payment processors (Stripe), SaaS APIs (Slack, Twilio), or internal services.

When to Consider This Package

• Adopt if:

  • Your Symfony app uses Guzzle HTTP clients (e.g., for external APIs, webhooks, or service-to-service communication).
  • You need distributed tracing (OpenTelemetry/OpenTracing) with minimal code changes—this package auto-injects tracing headers into Guzzle requests.
  • Your stack includes Symfony 4–6, PHP 8+, and a tracing backend (e.g., Jaeger, Zipkin, Datadog).
  • You’re already using or planning to use OpentracingBundle-core (required dependency).

• Look elsewhere if:

  • You’re not using Guzzle (e.g., rely on Symfony’s HttpClient or cURL directly). For HttpClient, consider symfony/http-client-opentracing.
  • You need active maintenance—the package has no open issues, but the last release was in 2023 (check for forks or alternatives like OpenTelemetry PHP).
  • Your team lacks observability maturity—distributed tracing requires backend support (e.g., Jaeger) and cultural buy-in for instrumenting spans.
  • You’re using Symfony 3 (unsupported; requires Symfony 4+).
  • You need advanced features like custom span naming or context propagation beyond HTTP headers (may require extending the bundle).

How to Pitch It (Stakeholders)

For Executives:

"This package lets us add real-time visibility into how our Symfony services interact with each other and third-party APIs—without writing custom tracing code. For example, if a payment fails in our checkout flow, we’ll instantly see whether the issue is in our service, the payment processor’s API, or the network. It’s a low-effort, high-impact way to reduce debugging time for critical paths like transactions, user onboarding, or data syncs. The cost? Just a few lines of Composer config and integration with our existing observability tools like Jaeger. This aligns with our observability roadmap and will pay dividends in reliability and MTTR."

For Engineering Teams:

*"This bundle automatically instruments Guzzle HTTP clients with OpenTracing headers, so every external call (e.g., to Stripe, Slack, or our internal APIs) gets a span in your tracer. Key benefits:

• Zero code changes: Works out-of-the-box with existing Guzzle clients.
• Distributed context: Parent-child spans for nested requests (e.g., a user’s API call → payment service → fraud check).
• Backend agnostic: Compatible with Jaeger, Zipkin, or Datadog.
• Lightweight: ~50 lines of code, no runtime overhead for non-traced requests.

How to adopt:

1. Install OpentracingBundle-core (required).
2. Add auxmoney/opentracing-bundle-guzzle via Composer.
3. Enable the bundle (Symfony Flex handles this automatically).
4. Verify spans appear in your tracer for Guzzle calls.

Trade-offs:

• Requires a tracing backend (but we’re already using Jaeger).
• Limited to Guzzle (but covers 90% of our HTTP clients).
• No active issues, but the project is stable and well-tested.

Next steps:

• Spike to validate integration with our Jaeger setup.
• Document how to opt out of tracing for sensitive endpoints (e.g., PII APIs).
• Explore extending it for Symfony Messenger or PSR-18 clients later."*

Call to Action: "Let’s start with a pilot in the payments service—it’s the highest-risk area for external dependencies. If successful, we can roll this out to all Symfony services using Guzzle."