Api Laravel Package

Technical Evaluation

Architecture Fit

• Observability-First Alignment: The open-telemetry/api package is a core dependency for implementing OpenTelemetry in PHP/Laravel, enabling distributed tracing, metrics, and logging. It aligns perfectly with modern observability architectures, particularly for microservices, APIs, and event-driven systems.
• Laravel Compatibility: Laravel’s ecosystem (e.g., HTTP requests, queues, jobs, and service containers) is natively instrumentable via OpenTelemetry’s auto-instrumentation hooks and middleware. The package’s Span, Meter, and Logger interfaces integrate seamlessly with Laravel’s event system and service providers.
• Extensibility: The API is modular—it defines contracts (e.g., InstrumentationInterface, SpanProcessor) that can be implemented by Laravel-specific SDKs (e.g., open-telemetry/sdk). This allows TPMs to swap implementations without breaking application logic.

Integration Feasibility

• Low Friction for Laravel:
  • Service Provider Integration: The API can be bootstrapped in Laravel’s AppServiceProvider via a singleton OpenTelemetry\API\GlobalOpenTelemetry instance.
  • Middleware Support: HTTP spans can be auto-instrumented using Laravel’s middleware pipeline (e.g., OpenTelemetry\Instrumentation\Http\ServerMiddleware).
  • Queue/Job Instrumentation: Laravel’s Illuminate\Queue and Illuminate\Bus can be instrumented via OpenTelemetry’s Span context propagation.
• Dependency Graph:
  • No Direct Dependents: The package is a pure API layer with zero runtime dependencies, reducing bloat and conflicts.
  • SDK Required: To export data (e.g., to Jaeger, Prometheus), a separate SDK (e.g., open-telemetry/sdk) is needed. This is a deliberate design to decouple API from exporters.

Technical Risk

• Breaking Changes:
  • Deprecated Interfaces: InstrumentationInterface and ConfigurationResolver are deprecated (v1.9.0+). TPMs must migrate to newer patterns (e.g., InstrumentationLibrary).
  • PHP Version Support: Dropped PHP 7.4/8.0 support (v1.1.0beta1+). Ensure Laravel’s PHP version (≥8.1) is compatible.
• Complexity:
  • Context Propagation: Manual context management (e.g., SpanContext) is required for cross-service tracing. Laravel’s service container can simplify this via dependency injection.
  • Resource Overhead: Spans/metrics add minimal overhead (~1–5% latency), but unbounded spans (e.g., leaks) can degrade performance. Use SpanProcessor to limit retention.
• Tooling Gaps:
  • Laravel-Specific Docs: Limited Laravel-focused guides exist. TPMs must rely on OpenTelemetry’s PHP docs and Laravel’s observability extensions.

Key Questions for TPM

1. Instrumentation Scope:
   • Should we instrument all HTTP routes, or only critical paths (e.g., /api/payments)?
   • How will we handle third-party services (e.g., Stripe, AWS SDK) for cross-service tracing?
2. Data Export Strategy:
   • Which exporter will we use (e.g., OTLP, Jaeger, Zipkin)? Does it support Laravel’s async queues?
   • How will we sample traces (e.g., 100% for errors, 1% for others)?
3. Cost vs. Value:
   • What’s the ROI threshold for observability? (e.g., "We’ll instrument if MTTR improves by >30%.")
   • Will we use auto-instrumentation or manual spans for business logic?
4. Operational Ownership:
   • Who will manage span limits (e.g., max 100 active spans per request)?
   • How will we alert on anomalies (e.g., high latency spans, missing traces)?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • HTTP: Integrate with Laravel’s Illuminate\Http\Request via middleware (e.g., OpenTelemetry\Instrumentation\Http\ServerMiddleware).
  • Queues/Jobs: Use OpenTelemetry\Instrumentation\Queue\QueueMiddleware to trace async jobs.
  • Database: Instrument Eloquent queries with OpenTelemetry\Instrumentation\Database\QuerySpan.
  • Logging: Replace Monolog handlers with OpenTelemetry\Instrumentation\Logger\LoggerHandler.
• PHP Extensions:
  • PDO: Use OpenTelemetry\Instrumentation\Pdo\PdoSpan for database spans.
  • gRPC: Leverage OpenTelemetry\Instrumentation\Grpc\GrpcSpan if using Laravel Octane.
• Async Support:
  • Laravel’s Illuminate\Bus and Illuminate\Queue can propagate SpanContext via Span::storeInBaggage().

Migration Path

1. Phase 1: API Integration (Low Risk)
   • Add open-telemetry/api to composer.json:

     composer require open-telemetry/api
     

   • Bootstrap in AppServiceProvider:

     use OpenTelemetry\API\GlobalOpenTelemetry;
     use OpenTelemetry\API\Common\Instrumentation\InstrumentationLibrary;
     
     public function boot()
     {
         $library = InstrumentationLibrary::create('laravel-app');
         GlobalOpenTelemetry::getMeterProvider()->registerInstrumentationLibrary($library);
     }
     

2. Phase 2: Auto-Instrumentation (Medium Risk)
   • Add middleware for HTTP/queues:

     // app/Http/Kernel.php
     protected $middleware = [
         \OpenTelemetry\Instrumentation\Http\ServerMiddleware::class,
     ];
     

   • Configure sampling (e.g., AlwaysOnSampler for dev, ProbabilitySampler for prod).
3. Phase 3: SDK + Exporter (High Risk)
   • Add an SDK (e.g., open-telemetry/sdk) and configure an exporter (e.g., OTLP):

     use OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessor;
     use OpenTelemetry\SDK\Trace\Export\OtlpHttpSpanExporter;
     
     $exporter = new OtlpHttpSpanExporter('http://otel-collector:4318/v1/traces');
     GlobalOpenTelemetry::getTracerProvider()->addSpanProcessor(
         new BatchSpanProcessor($exporter)
     );
     

4. Phase 4: Custom Instrumentation (Optional)
   • Add manual spans for business logic:

     $tracer = GlobalOpenTelemetry::getTracer('laravel-app');
     $span = $tracer->spanBuilder('process-order')->startSpan();
     try {
         $span->addEvent('order-created', ['order_id' => $order->id]);
         // Business logic...
     } finally {
         $span->end();
     }
     

Compatibility

• Laravel Versions:
  • Tested on Laravel 9+ (PHP 8.1+). Laravel 8 may require polyfills.
• Existing Observability Tools:
  • Prometheus: Use open-telemetry/sdk-metrics to expose Laravel metrics (e.g., http.server.duration).
  • ELK: Export logs via OpenTelemetry\Instrumentation\Logger\LoggerHandler to OTLP.
• Third-Party Packages:
  • Laravel Telescope: Can be extended to include OpenTelemetry spans.
  • Sentry: Use OpenTelemetry’s ErrorHandler to enrich Sentry events.

Sequencing

Operational Impact

Maintenance

• Dependency Updates:
  • The API is stable (v1.x), but SDKs (e.g., open-telemetry/sdk) may introduce breaking changes. Pin versions in composer.json:

    "open-telemetry/api": "^1.9",
    "open-telemetry/sdk": "^1.9"
    

• **Deprec