Opentracing Bundle Jaeger Laravel Package

Technical Evaluation

Architecture Fit

• Microservices/Monolithic Compatibility: Fits seamlessly into Symfony/Laravel applications (via Symfony bundles) where distributed tracing is required. Laravel’s lack of native Symfony support may require a Symfony bridge (e.g., symfony/console or symfony/http-client for compatibility).
• Tracing Granularity: Supports request-level sampling (probabilistic/constant) and header-based trace propagation, ideal for HTTP-based microservices or Laravel API layers.
• Instrumentation: Integrates with OpenTracing (deprecated but widely adopted), requiring minimal code changes if existing instrumentation uses opentracing-php.

Integration Feasibility

• Symfony Dependency: Requires Symfony components (e.g., HttpFoundation, DependencyInjection). For Laravel, a Symfony kernel wrapper (e.g., spatie/laravel-symfony-components) or custom bridge would be needed.
• Jaeger Agent/Collector: Assumes a Jaeger backend (agent/collector) is deployed. Compatibility with alternative backends (e.g., Zipkin) is not guaranteed.
• PSR-18 Support: Leverages PSR-18 HTTP clients (e.g., symfony/http-client), which can be adapted in Laravel via guzzlehttp/guzzle or symfony/http-client polyfills.

Technical Risk

• Laravel-Symfony Gap: High risk without a Symfony bridge. Workarounds include:
  • Using Laravel’s HTTP client (Guzzle) with manual OpenTracing instrumentation.
  • Wrapping Laravel in a Symfony microkernel for the tracing layer.
• Deprecation Risk: OpenTracing is deprecated in favor of OpenTelemetry. Migration path to OpenTelemetry PHP (e.g., open-telemetry/opentelemetry-php) should be planned.
• Sampling Overhead: Probabilistic sampling may introduce performance overhead if misconfigured (e.g., high sampling rates in high-throughput systems).

Key Questions

1. Symfony vs. Laravel: Is the team willing to adopt Symfony components or build a bridge?
2. Jaeger Backend: Is Jaeger already deployed, or will this require new infrastructure?
3. OpenTracing vs. OpenTelemetry: Should this be a short-term solution with a planned migration to OpenTelemetry?
4. Sampling Strategy: Will constant sampling (all requests) or probabilistic sampling (e.g., 1%) be used?
5. Instrumentation Scope: Will tracing extend to database queries, queues, or external APIs (beyond HTTP)?

Integration Approach

Stack Fit

• Symfony: Native fit with zero changes beyond bundle installation.
• Laravel: Requires one of three approaches:
  1. Symfony Bridge: Use spatie/laravel-symfony-components + symfony/http-client for HTTP instrumentation.
  2. Manual Instrumentation: Use opentracing-php directly with Laravel’s HTTP client (Guzzle).
  3. Hybrid Kernel: Embed a Symfony kernel alongside Laravel for tracing-only functionality.
• PHP Version: Supports PHP 8.0+ (LTS) and Symfony 5.4+ (or 6.x). Laravel 9/10 compatibility depends on the chosen approach.

Migration Path

1. Assess Current Tracing: Audit existing instrumentation (e.g., Monolog, custom logs) to identify gaps.
2. Symfony Compatibility Layer:
   • Install symfony/http-client and symfony/dependency-injection.
   • Use auxmoney/opentracing-bundle-core as a dependency.
3. Laravel-Specific Adaptations:
   • Override HttpClient to inject OpenTracing spans.
   • Use middleware to propagate trace headers (uber-trace-id).
4. Jaeger Setup:
   • Deploy Jaeger agent/collector (Docker or Kubernetes).
   • Configure AUXMONEY_OPENTRACING_SAMPLER_CLASS (e.g., ProbabilisticSampler with 0.01 for 1% sampling).

Compatibility

Sequencing

1. Phase 1: Instrument HTTP endpoints (Symfony/Laravel routes).
2. Phase 2: Extend to external API calls (Guzzle/Symfony HTTP client).
3. Phase 3: Add database/queue tracing (requires custom instrumentation).
4. Phase 4: Plan OpenTelemetry migration (replace OpenTracing spans).

Operational Impact

Maintenance

• Bundle Updates: Low effort (Composer updates). Monitor for Symfony/PHP version drops.
• Jaeger Dependencies: Maintain Jaeger agent/collector (e.g., Docker images, Kubernetes manifests).
• Sampler Configuration: Adjust AUXMONEY_OPENTRACING_SAMPLER_VALUE for cost/performance tradeoffs.

Support

• Debugging: Jaeger UI provides trace visualization, but complex spans may require custom logging.
• Vendor Support: Community-driven (no official support). Issues should be raised on GitHub.
• Alternatives: If support gaps arise, consider OpenTelemetry PHP or Datadog APM.

Scaling

• Sampling Rate: Probabilistic sampling (e.g., 1%) reduces Jaeger backend load.
• Agent Saturation: Ensure Jaeger agents can handle span volume (scale horizontally if needed).
• Laravel Scaling: No direct impact, but HTTP client instrumentation must scale with request volume.

Failure Modes

Ramp-Up

• Development: 2–4 weeks for Symfony (1 week for Laravel with bridge).
• Key Tasks:
  1. Install bundle + configure Jaeger.
  2. Instrument critical endpoints first.
  3. Validate traces in Jaeger UI.
  4. Expand to non-HTTP components (queues, DB).
• Training: Team needs familiarity with distributed tracing concepts and Jaeger UI.
• Documentation: Limited; rely on auxmoney/OpentracingBundle-core docs and GitHub issues.