Api Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require open-telemetry/api
   

2. Initialize OpenTelemetry (requires a compatible SDK like open-telemetry/sdk):

   use OpenTelemetry\API\Common\Instrumentation\Configuration;
   use OpenTelemetry\API\Common\Instrumentation\ConfigurationProvider;
   use OpenTelemetry\API\Common\Instrumentation\HookManager;
   
   // Initialize configuration (example with file-based config)
   $config = Configuration::fromFile(__DIR__ . '/otel-config.yaml');
   $provider = new ConfigurationProvider($config);
   
   // Register hooks (e.g., for auto-instrumentation)
   HookManager::registerHooks();
   

3. First Use Case: Tracing a Request

   use OpenTelemetry\API\Trace\TracerInterface;
   use OpenTelemetry\API\Trace\Span;
   
   $tracer = \OpenTelemetry\API\GlobalTracer::getTracer('my-app');
   $span = $tracer->spanBuilder('process-request')->startSpan();
   
   try {
       // Business logic here
       $span->addEvent('request-processed');
   } finally {
       $span->end();
   }
   

Key Entry Points

• Tracing: GlobalTracer::getTracer() for spans.
• Metrics: GlobalMeter::getMeter() for counters, gauges, etc.
• Logs: GlobalLogger::getLogger() for structured logging.
• Context Propagation: Propagator::getTextMapPropagator() for HTTP/async contexts.

Implementation Patterns

Core Workflows

1. Tracing Workflow

• Manual Spans:

  $span = $tracer->spanBuilder('user-auth')
      ->setAttribute('user.id', $userId)
      ->startSpan();
  
  // Nest spans
  $dbSpan = $tracer->spanBuilder('query-db')
      ->setParent($span)
      ->startSpan();
  
  $dbSpan->end();
  $span->end();
  

• Auto-Instrumentation: Use HookManager::registerHooks() to auto-instrument HTTP requests, database queries, etc.

  HookManager::registerHooks([
      'http' => true,
      'pdo' => true,
  ]);
  

2. Metrics Workflow

• Counters:

  $counter = $meter->getCounter('api.requests');
  $counter->add(1, ['method' => 'GET']);
  

• Histograms:

  $histogram = $meter->getHistogram('api.latency');
  $histogram->record($executionTime, ['endpoint' => '/users']);
  

3. Context Propagation

• HTTP Requests:

  $propagator = Propagator::getTextMapPropagator();
  $carrier = []; // e.g., $_SERVER or custom array
  $propagator->inject($carrier, \OpenTelemetry\Context\Context::current());
  
  // Later, extract context
  $context = $propagator->extract($carrier);
  \OpenTelemetry\Context\Context::storage()->activate($context);
  

4. Logging

• Structured Logs:

  $logger = \OpenTelemetry\API\Logs\GlobalLogger::getLogger('my-app');
  $logger->logRecordBuilder()
      ->setSeverityText('info')
      ->setBody('User logged in')
      ->setAttribute('user.id', $userId)
      ->emit();
  

Laravel-Specific Patterns

1. Service Provider Integration:

   // In AppServiceProvider::boot()
   $this->app->singleton(TracerInterface::class, function () {
       return \OpenTelemetry\API\GlobalTracer::getTracer('laravel-app');
   });
   

2. Middleware for Tracing:

   use OpenTelemetry\API\Trace\TracerInterface;
   
   class TraceMiddleware
   {
       public function __construct(private TracerInterface $tracer) {}
   
       public function handle($request, Closure $next)
       {
           $span = $this->tracer->spanBuilder('http.request')
               ->setAttribute('http.method', $request->method())
               ->setAttribute('http.url', $request->url())
               ->startSpan();
   
           try {
               return $next($request);
           } finally {
               $span->end();
           }
       }
   }
   

3. Queue Job Tracing:

   use OpenTelemetry\API\Trace\TracerInterface;
   
   class ProcessOrderJob implements ShouldQueue
   {
       public function __construct(private TracerInterface $tracer) {}
   
       public function handle()
       {
           $span = $this->tracer->spanBuilder('process-order')->startSpan();
           try {
               // Job logic
           } finally {
               $span->end();
           }
       }
   }
   

4. Database Query Tracing: Use the PDO hook (via HookManager) to auto-instrument queries:

   HookManager::registerHooks(['pdo' => true]);
   

Gotchas and Tips

Pitfalls

1. Deprecated Interfaces:

   • InstrumentationInterface and ConfigurationResolver are deprecated (since v1.9.0). Use ConfigurationProvider instead.
   • Example migration:

     // Old (deprecated)
     $configResolver = new InstrumentationInterface();
     
     // New
     $config = Configuration::fromEnv();
     $provider = new ConfigurationProvider($config);
     

2. Context Leaks:

   • Always ensure contexts are properly activated/deactivated in async operations (e.g., queues, HTTP clients).
   • Use Context::storage()->activate($context) and Context::storage()->deactivate($context).

3. Span Suppression:

   • Spans may be suppressed if they exceed configured limits. Check Span::isRecording() before adding events/attributes.

4. Attribute Validation:

   • Attributes with non-homogenous array values (e.g., mixed string/int) are dropped. Ensure consistent types:

     // Bad (may be dropped)
     $span->setAttribute('tags', ['key1' => 'value1', 'key2' => 123]);
     
     // Good
     $span->setAttribute('tags', ['key1' => 'value1', 'key2' => '123']);
     

5. Logger Deprecations:

   • EventLogger is deprecated. Use GlobalLogger for structured logging.

Debugging Tips

1. Enable Debug Logging: Set the OTEL_LOG_LEVEL environment variable:

   export OTEL_LOG_LEVEL=debug
   

   Or in code:

   putenv('OTEL_LOG_LEVEL=debug');
   

2. Span Debugging:

   • Use Span::setAttribute('debug', true) to mark spans for detailed logging.
   • Check Span::getStatus() for errors:

     if (!$span->getStatus()->isOk()) {
         error_log('Span failed: ' . $span->getStatus()->getDescription());
     }
     

3. Context Propagation Issues:

   • Verify carrier keys (e.g., traceparent, tracestate) are correctly injected/extracted.
   • Use Propagator::getTextMapPropagator()->getKeys() to inspect expected keys.

4. Performance Overhead:

   • Disable auto-instrumentation for high-frequency operations (e.g., loops):

     HookManager::registerHooks(['pdo' => false]); // Disable PDO hook
     

Extension Points

1. Custom Propagators: Implement PropagatorInterface for custom context propagation (e.g., gRPC, Kafka):

   class CustomPropagator implements PropagatorInterface {
       public function inject(Context $context, array &$carrier) { /* ... */ }
       public function extract(array $carrier): Context { /* ... */ }
   }
   

2. Span Processors: Use SpanProcessorInterface to filter/modify spans before export:

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

3. Resource Attributes: Add custom resource attributes (e.g., service version) via ResourceInfo:

   $resource = ResourceInfo::create([
       'service.version' => '1.0.0',
       'deployment.environment' => 'production',
   ]);
   

4. Hook Customization: Extend auto-instrumentation hooks by implementing HookInterface:

   class CustomHook implements HookInterface {
       public function handle(InstrumentationContext $context) {
           // Custom logic (e.g., modify spans before they're recorded)