Sdk Laravel Package

Technical Evaluation

Architecture Fit

• Observability Alignment: The OpenTelemetry PHP SDK is a strong fit for Laravel applications requiring distributed tracing, metrics, and logging. It integrates seamlessly with Laravel’s HTTP layer (via middleware), queue workers, and CLI commands, enabling end-to-end observability.
• Laravel Ecosystem Compatibility: Supports Laravel’s service container (via bind()), event listeners, and middleware hooks. Works with Laravel’s built-in HTTP client (Guzzle) and queue systems (via Span propagation).
• Modularity: The SDK’s plugin-based architecture (exporters, processors, samplers) allows selective adoption (e.g., start with tracing, add metrics later). Key components:
  • Tracing: Spans for HTTP requests, database queries, jobs.
  • Metrics: Custom counters, gauges, histograms.
  • Logs: Structured logging with trace context.

Integration Feasibility

• Low-Coupling Design: Uses context propagation (via Baggage and SpanContext) to attach telemetry to Laravel’s request lifecycle without monolithic instrumentation.
• Middleware Integration: Can wrap Laravel’s HandleIncomingRequest/HandleOutgoingResponse middleware to auto-instrument HTTP spans.
• Queue/Job Instrumentation: Supports Illuminate\Queue\Jobs\Job via Span propagation in job payloads.
• Database Instrumentation: Works with Laravel’s query builder (via PDO interceptors) or Eloquent events.

Technical Risk

Key Questions

1. Backend Compatibility:
   • Which OpenTelemetry backend (e.g., Jaeger, Honeycomb, Datadog) will ingest the data? Does it support the PHP SDK’s exporters?
2. Sampling Strategy:
   • Should we use head-based sampling (for APIs) or tail-based sampling (for batch processing)?
3. Resource Detection:
   • Does Laravel’s environment (e.g., Docker, serverless) require custom resource detectors (e.g., ServiceInfo)?
4. Legacy Code:
   • How will existing Monolog/Stackdriver logging integrate with OpenTelemetry logs?
5. Cost vs. Granularity:
   • Should we instrument all HTTP routes or only critical paths (e.g., /api/payments)?

Integration Approach

Stack Fit

• Laravel Core:
  • Middleware: Instrument Illuminate\Http\Middleware\HandleIncomingRequest to start spans on incoming requests.
  • Service Container: Bind TracerProvider and MeterProvider as singletons.
  • Events: Attach Span to Illuminate\Queue\Events\JobProcessed.
• HTTP Clients:
  • Guzzle: Use OpenTelemetry\Instrumentation\Guzzle for automatic span creation.
  • Symfony HTTP Client: Supported via OpenTelemetry\Instrumentation\SymfonyHttpClient.
• Databases:
  • PDO: Use OpenTelemetry\Instrumentation\PDO for query tracing.
  • Eloquent: Instrument Illuminate\Database\Eloquent\Model events (retrieved, saved).
• Queues:
  • Propagate SpanContext in job payloads using OpenTelemetry\Context\Propagation\TextMapPropagator.

Migration Path

1. Phase 1: Tracing (MVP)

   • Add open-telemetry/sdk and open-telemetry/exporter-otlp to composer.json.
   • Configure via .env:

     OTEL_PHP_AUTOLOAD_ENABLED=true
     OTEL_SERVICE_NAME="laravel-app"
     OTEL_EXPORTER_OTLP_ENDPOINT="http://jaeger:4317"
     

   • Instrument HTTP layer:

     // app/Http/Kernel.php
     protected $middlewareGroups = [
         'web' => [
             \OpenTelemetry\Instrumentation\Laravel\Http\Middleware\TraceHttp::class,
             // ...
         ],
     ];
     

   • Test with a single route (e.g., /health).

2. Phase 2: Metrics

   • Add custom metrics for business KPIs (e.g., user_signups_total).
   • Example:

     $meter = \OpenTelemetry\API\Globals::meterProvider()->getMeter('laravel');
     $counter = $meter->createCounter('user_signups');
     $counter->add(1, ['region' => 'us-west']);
     

3. Phase 3: Logs

   • Integrate with Laravel’s Log facade:

     use OpenTelemetry\API\Logs\Logger;
     $logger = \OpenTelemetry\API\Globals::loggerProvider()->getLogger('app');
     $logger->logRecordBuilder()
         ->setSeverityText('error')
         ->setBody('Failed to process payment')
         ->emit();
     

Compatibility

• Laravel Versions: Tested with Laravel 9+ (PHP 8.1+). For Laravel 8, use open-telemetry/api:1.5.
• PHP Extensions: Requires ctype, json, and pcntl (for sampling). No bcmath dependency.
• Exporter Support:
  • OTLP: Recommended for modern backends (e.g., Jaeger, Tempo).
  • Zipkin: Legacy support via open-telemetry/exporter-zipkin.
  • Console: For development (open-telemetry/exporter-console).

Sequencing

Operational Impact

Maintenance

• Configuration Management:
  • Centralize OpenTelemetry settings in .env or config/opentelemetry.php.
  • Use OTEL_CONFIG_FILE for complex setups (e.g., multiple environments).
• Dependency Updates:
  • Monitor open-telemetry/api and open-telemetry/sdk for breaking changes (quarterly reviews).
  • Pin versions in composer.json during stabilization:

    "open-telemetry/sdk": "^1.14",
    "open-telemetry/api": "^1.8"
    

• Logging:
  • Configure OpenTelemetry\SDK\Logs\Logger to drop sensitive attributes (e.g., passwords) via Logger::setAttributeDroppingStrategy.

Support

• Debugging:
  • Use OTEL_PHP_ERROR_MODE=always to log SDK errors to stderr.
  • Enable console exporter for local debugging:

    OTEL_PHP_EXPERIMENTAL_CONSOLE_EXPORTER_ENABLED=true
    

• Common Issues:
  • Missing Spans: Verify TextMapPropagator is registered and context is propagated.
  • High Cardinality: Use AttributeFilter to limit metric attributes.
  • Exporter Failures: Implement retry logic with OpenTelemetry\SDK\Common\Retry.

Scaling

• Sampling:
  • For high-throughput systems, use probabilistic sampling (e.g., TraceIdRatioBasedSampler with ratio 0.1).
  • Example:

    $sampler = new \OpenTelemetry\SDK\Trace\Sampler\TraceIdRatioBasedSampler(0.1);
    $provider = new \OpenTelemetry\SDK\Trace\TracerProvider($sampler);
    

• Batch Exporting:
  • Configure OTEL_EXPORTER_OTLP_BATCH_SPAN_PROCESSOR to reduce backend load.
• Resource Limits:
  • Monitor memory usage with OTEL_PHP_MEMORY_LIMIT_MB=256 (adjust based on workload).

Failure Modes

| Failure Scenario | Impact | Mitigation | |---------------------------------|--------------------------------