Sdk Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require open-telemetry/sdk
   

2. Enable autoloading (recommended for Laravel): Set these environment variables in .env:

   OTEL_PHP_AUTOLOAD_ENABLED=true
   OTEL_SERVICE_NAME=your-laravel-app
   OTEL_EXPORTER=otlp
   OTEL_EXPORTER_OTLP_ENDPOINT=http://your-collector:4318
   

3. First use case: Instrument a route or controller method:

   use OpenTelemetry\API\Globals;
   
   Route::get('/example', function () {
       $tracer = Globals::tracerProvider()->getTracer(__CLASS__);
       $span = $tracer->spanBuilder('route.example')->startSpan();
       $span->activate();
   
       // Your logic here
       $result = doSomething();
   
       $span->end();
       return $result;
   });
   

Key Entry Points

• Tracing: Globals::tracerProvider()->getTracer('your-service')
• Metrics: Globals::meterProvider()->getMeter('your-service')
• Logging: Globals::loggerProvider()->getLogger('your-service')

Laravel-Specific Quickstart

Add to bootstrap/app.php (after createApplication()):

$app->register(\OpenTelemetry\Contrib\Laravel\OpenTelemetryServiceProvider::class);

Implementation Patterns

1. Tracing Workflows

Auto-Instrumentation

• HTTP Requests: Automatically instruments Laravel HTTP clients (Guzzle, Symfony HTTP Client) via middleware.

  // In AppServiceProvider boot()
  $this->app->register(\OpenTelemetry\Contrib\Laravel\Http\OpenTelemetryMiddleware::class);
  

• Database Queries: Use opentelemetry/ext-db for PDO/Query Builder instrumentation.

Manual Spans

// Service layer
public function processOrder(Order $order) {
    $tracer = Globals::tracerProvider()->getTracer(__CLASS__);
    $span = $tracer->spanBuilder('order.process')
        ->setAttribute('order.id', $order->id)
        ->startSpan();

    try {
        $span->activate();
        // Business logic
        $span->setStatus(new Status(StatusCode::OK, 'Order processed'));
    } catch (\Exception $e) {
        $span->recordException($e);
        $span->setStatus(new Status(StatusCode::ERROR, $e->getMessage()));
        throw $e;
    } finally {
        $span->end();
    }
}

2. Metrics Collection

// Track API response times
$meter = Globals::meterProvider()->getMeter(__CLASS__);
$histogram = $meter->createHistogram('api.response.time', [
    'description' => 'API response time in milliseconds',
    'unit' => 'ms'
]);

// In your controller
$start = microtime(true);
$response = $client->request('GET', '/api/endpoint');
$histogram->record(microtime(true) - $start, [
    'endpoint' => 'api/endpoint',
    'status' => $response->getStatusCode()
]);

3. Logging Integration

// Structured logging with context
$logger = Globals::loggerProvider()->getLogger(__CLASS__);
$logger->info('Order processed', [
    'order_id' => $order->id,
    'user_id' => auth()->id(),
    'span_context' => Globals::span()->getSpanContext()
]);

4. Configuration Patterns

Environment Variables

# .env
OTEL_TRACES_SAMPLER=always_on  # For development
OTEL_TRACES_EXPORTER=console    # For local debugging
OTEL_METRICS_EXPORTER=otlp
OTEL_SERVICE_VERSION=1.0.0

Programmatic Configuration

use OpenTelemetry\SDK\Trace\Sampler\AlwaysOnSampler;
use OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor;

$tracerProvider = new TracerProvider(
    new SpanProcessor\BatchSpanProcessor(
        new SimpleSpanProcessor(),
        new AlwaysOnSampler()
    )
);
Globals::setTracerProvider($tracerProvider);

5. Laravel-Specific Patterns

Middleware for Automatic Context Propagation

// app/Http/Middleware/TraceContext.php
public function handle($request, Closure $next) {
    $propagator = new \OpenTelemetry\Context\Propagator\TextMapPropagator();
    $context = $propagator->extract(
        \OpenTelemetry\Context\Context::getCurrent(),
        $request->header()
    );

    return $next($request)->withHeaders(
        $propagator->inject($context, [])
    );
}

Service Provider Integration

// app/Providers/OpenTelemetryServiceProvider.php
public function register() {
    $this->app->singleton(TracerProvider::class, function () {
        return new TracerProvider(
            new BatchSpanProcessor(
                new OtlpSpanExporter([/* config */]),
                new AlwaysOnSampler()
            )
        );
    });
}

Gotchas and Tips

Common Pitfalls

1. Autoloading Failures

   • Issue: Globals::tracerProvider() returns a no-op if autoloading fails.
   • Fix: Explicitly configure the SDK in bootstrap/app.php:

     if (!Globals::tracerProvider()->getTracer('test')) {
         $provider = new TracerProvider();
         Globals::setTracerProvider($provider);
     }
     

2. Sampling Misconfiguration

   • Issue: TraceIdRatioBasedSampler with 0.0 ratio silently drops all traces.
   • Fix: Use AlwaysOnSampler in development:

     $sampler = new AlwaysOnSampler();
     

3. Resource Attributes Override

   • Issue: Custom resource attributes may be overwritten by auto-detectors.
   • Fix: Set attributes after SDK initialization:

     $resource = new Resource([
         'service.name' => 'your-app',
         'deployment.environment' => env('APP_ENV')
     ]);
     $provider = new TracerProvider([], $resource);
     

4. Span Context Leaks

   • Issue: Active spans may persist across requests in Laravel.
   • Fix: Clear context in middleware:

     public function terminate($request, $response) {
         Globals::span()->detach();
     }
     

5. Metric Naming Collisions

   • Issue: Multiple meters with same name create duplicate streams.
   • Fix: Use namespaced meters:

     $meter->getMeter('app.metrics.api');
     

Debugging Tips

1. Console Exporter for Local Testing

   OTEL_TRACES_EXPORTER=console
   OTEL_METRICS_EXPORTER=console
   OTEL_LOGS_EXPORTER=console
   

2. Span Visualization

   • Use span->setAttribute('http.url', $url) for better Jaeger/ZPages views.
   • Add span->setAttribute('db.statement', $query) for database spans.

3. Performance Overhead

   • Problem: High-volume metrics may impact performance.
   • Solution: Use MeterProvider with batching:

     $meterProvider = new MeterProvider([
         new PeriodicExportingMetricReader(
             new OtlpMetricExporter([/* config */]),
             5000 // Export every 5 seconds
         )
     ]);
     

Advanced Patterns

1. Custom Span Processors

   class FilteringSpanProcessor implements SpanProcessorInterface {
       public function onStart(Span $span, ?Span $parentSpan = null) {
           if ($span->getName() === 'internal.healthcheck') {
               $span->setAttribute('internal', true);
           }
       }
   
       public function onEnd(Span $span) {}
   }
   

2. Dynamic Configuration

   // Load config from cache
   $config = cache()->remember('otel_config', 60, function() {
       return \OpenTelemetry\SDK\Configuration::loadFromEnv();
   });
   

3. Laravel Job Instrumentation

   // In Handle trait
   public function handle() {
       $span = Globals::tracerProvider()->getTracer(__CLASS__)
           ->spanBuilder('job.'.class_basename($this))
           ->startSpan();
   
       try {
           $span->activate();
           // Job logic
       } finally {
           $span->end();
       }
   }
   

Configuration Quirks

1. OTEL_CONFIG_FILE Priority
   • File-based config (OTEL_CONFIG_FILE) overrides environment variables.
   • Example otel-config.yaml:

     exporters:
       otlp:
         endpoint