Sdk Laravel Package

Technical Evaluation

Architecture Fit

The OpenTelemetry PHP SDK aligns well with Laravel’s observability-first architecture, particularly for:

• Distributed tracing (via Span instrumentation) for microservices, queues, and HTTP clients.
• Metrics collection (via Meter) for performance monitoring (e.g., request latency, DB query counts).
• Logs instrumentation (via Logger) for structured logging with correlation IDs.
• Auto-instrumentation for frameworks like Symfony HTTP Client, Guzzle, and PSR-3 loggers (compatible with Laravel’s Log facade).

Key Fit Areas:

1. Laravel’s Service Container: The SDK integrates seamlessly via Globals::tracerProvider()/Globals::meterProvider(), enabling dependency injection.
2. Queue Workers: Supports async span propagation (e.g., Laravel\Queue\Jobs).
3. HTTP Middleware: Auto-instrumentation for Illuminate\Http\Request/Response via TextMapPropagator.
4. Database/ORM: Compatible with Laravel’s query builder (via Span context for SQL queries).

Integration Feasibility

Technical Risk

1. Performance Overhead:

   • Risk: Span creation/metrics collection may impact high-throughput endpoints.
   • Mitigation: Use AlwaysRecordSampler sparingly; configure batching (e.g., OtlpHttpExporter with export_interval).
   • Laravel-Specific: Test with queue:work and schedule:run under load.

2. Compatibility Gaps:

   • Risk: Laravel’s Event system lacks native OpenTelemetry support.
   • Mitigation: Use Meter for custom metrics (e.g., event.dispatching).
   • Risk: Older PHP versions (<8.1) may need polyfills (e.g., weaken for closures).
   • Mitigation: Target PHP 8.2+ for full feature support.

3. Configuration Complexity:

   • Risk: Environment variables (OTEL_*) and OTEL_CONFIG_FILE may conflict with Laravel’s .env.
   • Mitigation: Use Laravel’s config() binding for SDK config (e.g., config('opentelemetry.exporter')).

4. Exporter Dependencies:

   • Risk: OTLP exporters (e.g., otlp/otlp-http) require additional setup (e.g., Jaeger/Zipkin backend).
   • Mitigation: Start with ConsoleExporter for debugging, then migrate to OTLP.

Key Questions for TPM

1. Observability Goals:

   • Are we prioritizing traces, metrics, or logs? (e.g., traces for APIs, metrics for queues).
   • Should we use sampling (e.g., TraceIdRatioBasedSampler) to reduce volume?

2. Backend Integration:

   • Which OpenTelemetry Collector or backend (Jaeger, Honeycomb, Datadog) will we use?
   • Do we need custom attributes (e.g., Laravel’s auth()->user()->id) in spans?

3. Laravel-Specific Needs:

   • Should we instrument Eloquent queries or Job failures?
   • How will we handle legacy code (e.g., non-PSR-3 loggers)?

4. Operational Tradeoffs:

   • What’s the acceptable latency for span/metric collection?
   • Should we disable SDK in CI (via OTEL_PHP_AUTOLOAD_ENABLED=false)?

Integration Approach

Stack Fit

Migration Path

1. Phase 1: Instrumentation (Low Risk)

   • Add SDK via Composer:

     composer require open-telemetry/sdk open-telemetry/otlp
     

   • Enable autoloading in .env:

     OTEL_PHP_AUTOLOAD_ENABLED=true
     OTEL_SERVICE_NAME="laravel-app"
     OTEL_EXPORTER_OTLP_ENDPOINT="http://collector:4318"
     

   • Verify basic traces/metrics in ConsoleExporter (debug mode).

2. Phase 2: Core Integration (Medium Risk)

   • HTTP: Create middleware to propagate context:

     use OpenTelemetry\Context\Propagation;
     use OpenTelemetry\API\Globals;
     
     public function handle($request, Closure $next) {
         $carrier = new ArrayCarrier();
         Propagation::inject($carrier, Globals::getTextMapPropagator());
         $request->headers->add($carrier);
         return $next($request);
     }
     

   • Queues: Extend Illuminate\Queue\Jobs\Job to propagate context:

     public function handle() {
         $context = Propagation::extract(
             new ArrayCarrier($this->payload['headers']),
             Globals::getTextMapPropagator()
         );
         Propagation::setCurrentContext($context);
         // ... job logic
     }
     

3. Phase 3: Advanced Use Cases (High Risk)

   • Database: Instrument DB::listen():

     DB::listen(function ($query) {
         $span = Globals::tracerProvider()->getTracer('db')->startSpan($query->sql);
         // ... attach attributes
     });
     

   • Custom Metrics: Define business metrics:

     $meter = Globals::meterProvider()->getMeter('business');
     $updates = $meter->createCounter('user_updates');
     $updates->add(1, ['user_id' => auth()->id()]);
     

Compatibility

Sequencing

1. Start with Traces:
   • Instrument HTTP routes and queues first (highest ROI).
2. Add Metrics:
   • Focus on critical paths (e.g., API latency, queue processing time).
3. Logs Last:
   • Use Logger for structured logs with correlation IDs (requires backend support).

Avoid:

• Over-instrumenting early (e.g., adding spans to every Eloquent query).
• Mixing exporters (e.g., ConsoleExporter + OtlpExporter) during testing.

Operational Impact