Api Laravel Package

Technical Evaluation

Architecture Fit

• Observability Alignment: The open-telemetry/api package provides a standardized, vendor-neutral API for instrumenting Laravel applications with traces, metrics, and context propagation, aligning with modern observability best practices. It integrates seamlessly with OpenTelemetry’s ecosystem (e.g., Jaeger, Zipkin, Prometheus) and supports distributed tracing—critical for microservices and cloud-native Laravel deployments.
• Laravel Compatibility: Laravel’s ecosystem (e.g., Laravel Horizon, Scout, Echo) lacks native observability. This package enables fine-grained instrumentation of HTTP requests, database queries, queues, and background jobs, filling a gap in Laravel’s observability tooling.
• Extensibility: The API is modular—it defines interfaces (e.g., Span, Meter, Propagator) that can be implemented by backend services (e.g., OTLP exporters). This allows TPMs to swap implementations (e.g., switch from Jaeger to Honeycomb) without refactoring instrumentation logic.

Integration Feasibility

• Low Friction for Laravel: The package is PHP-first and leverages PSR-compatible patterns (e.g., dependency injection). Laravel’s Service Container can natively resolve OpenTelemetry interfaces, reducing boilerplate.
  • Example: Bind OpenTelemetry\API\Trace\TracerInterface to a concrete tracer (e.g., OpenTelemetry\SDK\Trace\Tracer) in AppServiceProvider.
• Middleware Integration: HTTP tracing can be added via Laravel middleware (e.g., OpenTelemetry\Contrib\HTTP\TraceMiddleware), auto-instrumenting routes, exceptions, and responses.
• Database/Queue Instrumentation: Libraries like opentelemetry-php/db (for PDO) or custom listeners for Laravel Events (illuminate\queue\JobProcessed) can extend instrumentation.

Technical Risk

• Breaking Changes: The package has deprecated interfaces (e.g., InstrumentationInterface in v1.9.0) and active refactoring (e.g., logger changes). A TPM must:
  • Pin to a stable version (e.g., 1.8.x) and monitor upstream deprecations.
  • Plan for migration paths if Laravel upgrades PHP (e.g., PHP 8.4+ fixes in v1.1.0beta1).
• Performance Overhead: Tracing/metrics add CPU/memory overhead. Benchmark critical paths (e.g., high-traffic APIs) to ensure latency SLAs are met.
• Exporter Dependencies: The API itself is lightweight, but exporters (e.g., OTLP, Zipkin) may introduce:
  • Network latency (for cloud exporters).
  • Schema evolution risks (e.g., OpenTelemetry semantic conventions).
• Context Propagation: Cross-service tracing requires W3C Trace Context headers. Ensure:
  • Laravel’s HTTP client (Guzzle) propagates headers.
  • Async workers (Queues) carry context via Baggage.

Key Questions

1. Observability Goals:
   • Are we prioritizing traces, metrics, or logs? (The API supports all but may require additional packages like opentelemetry-php/sdk.)
   • Do we need custom attributes (e.g., Laravel-specific tags like request_id)?
2. Exporter Strategy:
   • Will we use OTLP (recommended for cloud), Zipkin, or another backend?
   • How will we handle sampling (e.g., TraceFlags::SAMPLED)?
3. Laravel-Specific Needs:
   • Should we instrument Laravel Events (e.g., JobFailed) or Eloquent queries?
   • Will we need custom spans for business logic (e.g., payment processing)?
4. Operational Tradeoffs:
   • What’s the acceptable latency for tracing?
   • How will we debug sampling issues (e.g., dropped traces)?
5. Team Readiness:
   • Does the team have experience with distributed tracing?
   • Are developers familiar with OpenTelemetry concepts (spans, baggage, resources)?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • HTTP: Integrate with Laravel’s middleware pipeline (e.g., HandleIncomingRequest).
  • Database: Use opentelemetry-php/db for PDO instrumentation or wrap Eloquent queries.
  • Queues: Instrument illuminate\queue\Events (e.g., JobProcessed) or use opentelemetry-php/async for worker tracing.
  • Logging: Extend Laravel’s Log facade to emit structured logs with trace IDs.
• PHP Version: Requires PHP 8.1+ (Laravel 9+). Drop support for PHP 7.4/8.0 (per v1.2.0).
• Dependencies:
  • Core: open-telemetry/api (interfaces) + open-telemetry/sdk (concrete implementations).
  • Exporters: open-telemetry/exporter-otlp (recommended) or open-telemetry/exporter-zipkin.
  • Instrumentation: opentelemetry-php/http, opentelemetry-php/db, or custom packages.

Migration Path

1. Phase 1: Instrumentation (Low Risk)
   • Add open-telemetry/api and open-telemetry/sdk to composer.json.
   • Instrument critical paths (e.g., API routes, database queries) using middleware/listeners.
   • Example:

     // app/Providers/AppServiceProvider.php
     use OpenTelemetry\API\Trace\TracerInterface;
     use OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor;
     use OpenTelemetry\SDK\Trace\TracerProvider;
     
     public function register()
     {
         $tracerProvider = new TracerProvider();
         $tracerProvider->addSpanProcessor(new SimpleSpanProcessor());
         $this->app->singleton(TracerInterface::class, fn() => $tracerProvider->getTracer('laravel'));
     }
     

2. Phase 2: Exporter Setup (Medium Risk)
   • Configure an exporter (e.g., OTLP) and validate data flows to the backend.
   • Example OTLP exporter:

     use OpenTelemetry\SDK\Trace\Exporter\Otlp\OtlpSpanExporter;
     
     $exporter = new OtlpSpanExporter();
     $processor = new SimpleSpanProcessor($exporter);
     $tracerProvider->addSpanProcessor($processor);
     

3. Phase 3: Advanced Instrumentation (High Value)
   • Add custom spans for business logic (e.g., payment flows).
   • Instrument Laravel Events or Queues for end-to-end visibility.
   • Example: Queue job tracing:

     use OpenTelemetry\API\Trace\TracerInterface;
     
     class ProcessOrderJob implements ShouldQueue
     {
         public function handle(TracerInterface $tracer)
         {
             $span = $tracer->spanBuilder('process_order')->startSpan();
             try {
                 // Business logic
             } finally {
                 $span->end();
             }
         }
     }
     

Compatibility

• Laravel Versions:
  • Laravel 9/10: Full compatibility (PHP 8.1+).
  • Laravel 8: Possible with PHP 8.0 polyfills (but unsupported per v1.2.0).
• Existing Observability Tools:
  • Prometheus: Use open-telemetry/exporter-prometheus for metrics.
  • ELK/Logstash: Emit logs with trace IDs for correlation.
• Third-Party Packages:
  • Guzzle HTTP Client: Use opentelemetry-php/http for automatic header propagation.
  • Redis/Predis: Instrument commands with custom spans.

Sequencing

1. Start with Traces:
   • Instrument HTTP requests and database queries first (highest ROI).
2. Add Metrics Later:
   • Use Meter for custom metrics (e.g., order_processing_time).
3. Optimize Sampling:
   • Configure head-based sampling (e.g., TraceFlags::SAMPLED) to reduce volume.
4. Validate with APM Tools:
   • Use Jaeger or Honeycomb to verify trace data quality.

Operational Impact

Maintenance

• Dependency Management:
  • Pin open-telemetry/api to a stable minor version (e.g., ^1.8) to avoid breaking changes.
  • Monitor the OpenTelemetry PHP GitHub for deprecations.
• Configuration Drift:
  • Centralize OpenTelemetry config (e.g., sampling rules, exporter endpoints) in **environment variables