Sdk Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require open-telemetry/sdk
   

2. Enable autoloading (recommended for Laravel): Add to .env:

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

3. First use case: Instrument a route handler:

   use OpenTelemetry\API\Globals;
   
   Route::get('/tracked', function () {
       $tracer = Globals::tracerProvider()->getTracer(__CLASS__);
       $span = $tracer->spanBuilder('route-handler')->startSpan();
       $span->setAttribute('http.route', route()->getName());
   
       try {
           // Your logic here
           $span->setStatusCode(200);
       } finally {
           $span->end();
       }
   });
   

Key Starting Points

• SDK Builder: For programmatic configuration (see examples/sdk_builder.php).
• Environment Variables: Full list here.
• Laravel Integration: Use otlp exporter with laravel-otel package (if available) or configure manually.

Implementation Patterns

Core Workflows

1. Tracing

// Auto-instrumentation (HTTP, DB, Queues)
$tracerProvider = new \OpenTelemetry\SDK\Trace\TracerProvider();
$tracerProvider->addSpanProcessor(new \OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor(
    new \OpenTelemetry\SDK\Trace\SpanExporter\ConsoleSpanExporter()
));

// Manual spans
$span = $tracer->spanBuilder('user-service')
    ->setAttribute('user.id', $userId)
    ->startSpan();
$span->addEvent('event-name', ['key' => 'value']);
$span->end();

2. Metrics

$meter = Globals::meterProvider()->getMeter('app.metrics');
$counter = $meter->createCounter('request.count');
$counter->add(1, ['route' => 'home']);

3. Context Propagation

// Extract context from HTTP headers
$carrier = [];
$context = \OpenTelemetry\Context\Propagator\TextMapPropagator::extract(
    $carrier,
    new \ArrayAccessArrayAccess($request->header())
);

// Inject into outbound requests
$outboundCarrier = [];
\OpenTelemetry\Context\Propagator\TextMapPropagator::inject(
    $context,
    $outboundCarrier,
    new \ArrayAccessArrayAccess($response->headers)
);

4. Resource Configuration

$resource = new \OpenTelemetry\SemConv\ResourceInfo(
    'your-service',
    '1.0.0',
    'PHP',
    'production'
);
$resource->addAttribute('deployment.environment', 'staging');

Laravel-Specific Patterns

1. Service Provider Bootstrapping:

   public function boot()
   {
       $this->configureOtel();
   }
   
   protected function configureOtel()
   {
       $tracerProvider = new \OpenTelemetry\SDK\Trace\TracerProvider();
       $tracerProvider->register();
       // Add exporters, processors, etc.
   }
   

2. Middleware for Auto-Tracing:

   public function handle($request, Closure $next)
   {
       $tracer = Globals::tracerProvider()->getTracer('laravel-middleware');
       $span = $tracer->spanBuilder('middleware')
           ->setAttribute('http.method', $request->method())
           ->startSpan();
   
       try {
           return $next($request);
       } finally {
           $span->end();
       }
   }
   

3. Queue Job Instrumentation:

   public function handle()
   {
       $tracer = Globals::tracerProvider()->getTracer('queue-job');
       $span = $tracer->spanBuilder('process-payment')
           ->setAttribute('job.id', $this->job->id)
           ->startSpan();
   
       try {
           // Job logic
       } finally {
           $span->end();
       }
   }
   

Integration Tips

• Database: Use doctrine-dbal-otel or laravel-otel-db for auto-instrumentation.
• HTTP Clients: Wrap Guzzle/Symfony HTTP clients with Http\Client\Instrumentation.
• Logging: Use OpenTelemetry\SDK\Logs\Logger for structured logs with trace context.
• Sampling: Configure TraceIdRatioBasedSampler or AlwaysOnSampler via environment variables:

  OTEL_TRACES_SAMPLER=TraceIdRatioBased
  OTEL_TRACES_SAMPLER_ARG=0.1  # 10% sampling rate
  

Gotchas and Tips

Pitfalls

1. Autoloading Quirks:

   • If OTEL_PHP_AUTOLOAD_ENABLED=true but config is missing, the SDK returns no-op implementations.
   • Fix: Validate environment variables or use programmatic setup.

2. Span Leaks:

   • Unended spans consume memory. Always use try-finally or context managers:

     $span = $tracer->spanBuilder('operation')->startSpan();
     // ...
     $span->end(); // Critical!
     

3. Attribute Limits:

   • Exporters may drop attributes exceeding limits (e.g., OTLP max 128 attributes per span).
   • Tip: Use Span::setStatus() for critical metadata instead of attributes.

4. Context Propagation:

   • Forgetting to propagate context between services breaks trace continuity.
   • Tip: Use Context::with() for explicit context management:

     $context = Context::with(\OpenTelemetry\Context\Context::getCurrent(), $span);
     

5. Exporter Failures:

   • Silent failures in exporters (e.g., OTLP endpoint unreachable) may go unnoticed.
   • Tip: Configure a ConsoleSpanExporter as fallback:

     $exporter = new \OpenTelemetry\SDK\Trace\SpanExporter\ConsoleSpanExporter();
     $processor = new \OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessor($exporter);
     

Debugging Tips

1. Enable Debug Logging:

   OTEL_PHP_LOG_LEVEL=debug
   OTEL_PHP_LOG_FILE=storage/logs/otel.log
   

2. Validate Configuration:

   $config = \OpenTelemetry\SDK\Common\Configuration::getDefault();
   dump($config->toArray());
   

3. Check for Deprecated APIs:

   • Meter::isEnabled() was removed in v1.1.0. Use MeterProvider::getMeter() directly.

4. Memory Profiling:

   • Use SpanProcessor\SimpleSpanProcessor for development to avoid batching overhead.

Extension Points

1. Custom Span Processors:

   class CustomProcessor implements \OpenTelemetry\SDK\Trace\SpanProcessor\SpanProcessorInterface
   {
       public function onStart(\OpenTelemetry\SDK\Trace\Span $span) {}
       public function onEnd(\OpenTelemetry\SDK\Trace\Span $span) {
           if ($span->getStatus()->isError()) {
               // Custom error handling
           }
       }
       public function shutdown() {}
   }
   

2. Dynamic Resource Attributes:

   $resource = new \OpenTelemetry\SemConv\ResourceInfo(...);
   $resource->addDetector(new class implements \OpenTelemetry\SDK\Resource\ResourceDetectorInterface {
       public function detect(): array {
           return ['custom.attr' => config('app.env')];
       }
   });
   

3. Sampler Overrides:

   $sampler = new \OpenTelemetry\SDK\Trace\Sampler\AlwaysOnSampler();
   $tracerProvider = new \OpenTelemetry\SDK\Trace\TracerProvider();
   $tracerProvider->setSampler($sampler);
   

4. Exporter Chaining:

   $primaryExporter = new \OpenTelemetry\SDK\Trace\SpanExporter\OtlpSpanExporter();
   $fallbackExporter = new \OpenTelemetry\SDK\Trace\SpanExporter\ConsoleSpanExporter();
   $processor = new \OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessor(
       new \OpenTelemetry\SDK\Trace\SpanExporter\CompositeSpanExporter([$primaryExporter, $fallbackExporter])
   );
   

Laravel-Specific Gotchas

1. Service Container Conflicts:
   • Avoid binding `Globals::