Api Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require open-telemetry/api
   

   (Note: This is a pure API package—you'll need an SDK like open-telemetry/sdk for implementation.)

2. First use case: Instrumenting a route

   use OpenTelemetry\API\Trace\TracerInterface;
   use OpenTelemetry\API\Trace\Span;
   
   // Get the tracer (via SDK or DI container)
   $tracer = \OpenTelemetry\API\GlobalTracer::getTracer('my-app');
   
   // Start a span
   $span = $tracer->spanBuilder('user.route')
       ->setAttribute('http.method', 'GET')
       ->startSpan();
   
   try {
       // Your route logic here
       $span->addEvent('route.processed');
   } finally {
       $span->end();
   }
   

3. Key entry points:

   • GlobalTracer::getTracer() – For trace instrumentation.
   • GlobalMeter::getMeter() – For metrics.
   • GlobalPropagation::getTextMapPropagator() – For context propagation.

Implementation Patterns

1. Trace Instrumentation

Workflow: HTTP Requests

use OpenTelemetry\API\Trace\Span;
use OpenTelemetry\API\Trace\Status;

$span = \OpenTelemetry\API\GlobalTracer::getTracer('my-app')->spanBuilder('http.request')
    ->setAttribute('http.url', $request->getUri())
    ->setAttribute('http.method', $request->getMethod())
    ->startSpan();

try {
    $response = $client->send($request);
    $span->setAttribute('http.status_code', $response->getStatusCode());
} catch (\Exception $e) {
    $span->recordException($e);
    $span->setStatus(new Status(Status::ERROR, $e->getMessage()));
} finally {
    $span->end();
}

Nested Spans

$parentSpan = \OpenTelemetry\API\GlobalTracer::getTracer('my-app')->getCurrentSpan();
$childSpan = $parentSpan->tracer()->spanBuilder('db.query')
    ->setParent($parentSpan)
    ->startSpan();

2. Metrics

Counter Example

$meter = \OpenTelemetry\API\GlobalMeter::getMeter('my-app');
$counter = $meter->createCounter('request.count');
$counter->add(1, ['http.method' => 'GET']);

Histogram for Latency

$histogram = $meter->createHistogram('request.latency.ms');
$histogram->record($executionTimeMs, ['route' => 'user.profile']);

3. Context Propagation

Outgoing Requests

use OpenTelemetry\API\Propagation\TextMapPropagator;

$propagator = \OpenTelemetry\API\GlobalPropagation::getTextMapPropagator();
$carrier = [];
$propagator->inject($carrier, \OpenTelemetry\API\GlobalContext::getCurrent());

// Send $carrier with HTTP headers
$client->send($request->withHeaders($carrier));

Incoming Requests

$propagator->extract($carrier, $request->getHeaders());
\OpenTelemetry\API\GlobalContext::storeInContext($carrier);

4. Auto-Instrumentation Hooks

\OpenTelemetry\API\Instrumentation\Hook::register(
    \OpenTelemetry\API\Instrumentation\Hook::HTTP_CLIENT,
    function ($url, $options, $next) {
        $span = \OpenTelemetry\API\GlobalTracer::getTracer('my-app')->spanBuilder('http.client')
            ->setAttribute('http.url', $url)
            ->startSpan();

        try {
            $response = $next($url, $options);
            $span->setAttribute('http.status_code', $response->getStatusCode());
            return $response;
        } finally {
            $span->end();
        }
    }
);

Gotchas and Tips

1. API vs. SDK

• This package is only the API. You must pair it with an SDK (e.g., open-telemetry/sdk) for actual telemetry collection.
• Example SDK setup:

  composer require open-telemetry/sdk
  

2. Context Management

• Always use try/finally when working with spans to avoid memory leaks:

  $span->end(); // Critical!
  

• Avoid long-lived spans: End spans as soon as possible to prevent context pollution.

3. Deprecations

• InstrumentationInterface and ConfigurationResolver are deprecated (since v1.9.0). Use SDK-specific config instead.

4. Performance Tips

• Reuse span builders for common operations (e.g., database queries).
• Batch metric updates where possible to reduce overhead.

5. Debugging

• Enable logging via environment variable:

  export OTEL_LOG_LEVEL=debug
  

• Check for missing context: Use GlobalContext::getCurrent() to verify active spans.

6. Common Pitfalls

7. Extending the API

• Custom attributes: Use SpanAttribute for type-safe attributes.
• Hooks: Register auto-instrumentation hooks early (e.g., in bootstrap/app.php).
• Metrics: Implement ObservableInstrument for custom metric collection.

8. Laravel-Specific Tips

• Service Provider Setup:

  use OpenTelemetry\API\GlobalTracer;
  
  public function register()
  {
      $this->app->singleton(TracerInterface::class, function () {
          return GlobalTracer::getTracer('laravel-app');
      });
  }
  

• Middleware for Traces:

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