Telemetry Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require flow-php/telemetry
   

   Ensure compatibility with Laravel 10/11 (PHP 8.3+).

2. Basic Initialization: Since there’s no Laravel service provider, manually bind the Telemetry class in AppServiceProvider:

   use Flow\Telemetry\Telemetry;
   
   public function register()
   {
       $this->app->singleton(Telemetry::class, fn() => new Telemetry());
   }
   

3. First Use Case: Metrics Collection Track a simple counter (e.g., API requests):

   use Flow\Telemetry\Metrics\Counter;
   
   $counter = app(Telemetry::class)->counter('api.requests');
   $counter->increment();
   

4. First Use Case: Tracing Instrument a route or job with a span:

   use Flow\Telemetry\Tracing\Span;
   use Flow\Telemetry\Tracing\Tracer;
   
   $tracer = app(Telemetry::class)->tracer();
   $span = $tracer->startSpan('process.order');
   try {
       // Business logic
   } finally {
       $span->end();
   }
   

5. Configuration: Define exporters (e.g., Prometheus) in a custom config file (config/telemetry.php):

   return [
       'exporters' => [
           'prometheus' => [
               'host' => 'localhost',
               'port' => 9090,
           ],
       ],
   ];
   

   Load it via config() helper or service provider.

Implementation Patterns

Workflows

1. Metrics Collection:

   • Counters: Track discrete events (e.g., jobs.processed).

     $counter = app(Telemetry::class)->counter('jobs.processed');
     $counter->increment(5); // Batch increment
     

   • Gauges: Monitor real-time values (e.g., queue.size).

     $gauge = app(Telemetry::class)->gauge('queue.size');
     $gauge->set(100);
     

   • Histograms: Measure latency distributions (e.g., api.response.time).

     $histogram = app(Telemetry::class)->histogram('api.response.time');
     $histogram->record(150); // Milliseconds
     

2. Tracing:

   • Spans: Correlate execution (e.g., HTTP requests, database queries).

     $span = $tracer->startSpan('fetch.user', ['user_id' => 123]);
     $span->addEvent('query', ['sql' => 'SELECT * FROM users']);
     $span->end();
     

   • Context Propagation: Pass spans across service boundaries (e.g., HTTP clients).

     $context = $span->getContext();
     $client->withContext($context)->request(...);
     

3. Integration with Laravel:

   • Middleware: Auto-instrument HTTP requests.

     public function handle(Request $request, Closure $next)
     {
         $span = app(Tracer::class)->startSpan('http.request');
         try {
             return $next($request);
         } finally {
             $span->end();
         }
     }
     

   • Queue Jobs: Trace job execution.

     public function handle()
     {
         $span = app(Tracer::class)->startSpan('process.invoice');
         // Job logic
         $span->end();
     }
     

   • Events: Emit metrics for Laravel events.

     Event::listen(JobProcessed::class, function () {
         app(Telemetry::class)->counter('jobs.processed')->increment();
     });
     

4. Exporters:

   • Configure exporters in config/telemetry.php:

     'exporters' => [
         'prometheus' => [
             'host' => env('TELEMETRY_HOST', 'localhost'),
             'port' => env('TELEMETRY_PORT', 9090),
         ],
         'logging' => [
             'channel' => 'telemetry',
         ],
     ],
     

   • Use the Telemetry facade or service container to flush data:

     app(Telemetry::class)->flush();
     

Integration Tips

1. Avoid Tight Coupling:

   • Wrap Flow’s Telemetry in a Laravel-compatible interface (e.g., TelemetryService) to abstract Flow-specific details.
   • Example:

     class TelemetryService
     {
         public function counter(string $name): CounterInterface
         {
             return app(Telemetry::class)->counter($name);
         }
     }
     

2. Leverage Laravel Facades:

   • Create a Telemetry facade for cleaner syntax:

     // app/Facades/Telemetry.php
     public static function counter(string $name): CounterInterface
     {
         return app(TelemetryService::class)->counter($name);
     }
     

     Usage:

     Telemetry::counter('api.calls')->increment();
     

3. Batch Metrics:

   • Reduce overhead by batching metric flushes (e.g., every 5 seconds) in a scheduled job:

     use Illuminate\Support\Facades\Schedule;
     
     Schedule::call(function () {
         app(Telemetry::class)->flush();
     })->everyFiveSeconds();
     

4. Context Propagation:

   • For HTTP clients (e.g., Guzzle), propagate spans via middleware:

     $client = new Client([
         'handler' => HandlerStack::create([
             new SpanPropagationMiddleware($tracer),
         ]),
     ]);
     

5. Custom Exporters:

   • Implement a TelemetryExporter interface to support non-Prometheus backends (e.g., Datadog, InfluxDB):

     class DatadogExporter implements ExporterInterface
     {
         public function export(MetricData $data): void
         {
             // Send to Datadog API
         }
     }
     

Gotchas and Tips

Pitfalls

1. No Laravel Conventions:

   • Service Provider: Missing. Must manually bind Telemetry in AppServiceProvider.
   • Configuration: No config/telemetry.php by default. Requires custom setup.
   • Facades: No built-in facades. Must create your own (e.g., Telemetry facade).

2. Flow PHP Dependency:

   • Breaking Changes: The package is a subtree split from Flow PHP. Major Flow updates may break compatibility.
   • ETL Focus: Designed for ETL pipelines. Non-ETL use cases (e.g., APIs) may require workarounds.

3. Tracing Overhead:

   • Latency: Spans add ~1–5ms per operation. Test in production-like environments.
   • Context Propagation: Manual effort required for non-Flow services (e.g., HTTP clients).

4. Limited Documentation:

   • Laravel Examples: None. Rely on Flow PHP’s docs (may not apply).
   • Exporter Setup: Undocumented for non-Prometheus backends.

5. Metric Naming:

   • Collisions: No namespace enforcement. Use prefixes (e.g., laravel.api.) to avoid conflicts with Flow’s metrics.

Debugging

1. Metrics Not Appearing:

   • Check Exporter: Verify the exporter is configured and running (e.g., Prometheus server).
   • Flush Data: Call app(Telemetry::class)->flush() manually to debug.
   • Logging: Enable debug logging for the exporter:

     'exporters' => [
         'logging' => [
             'channel' => 'telemetry',
             'level' => 'debug',
         ],
     ],
     

2. Tracing Issues:

   • Missing Spans: Ensure spans are properly closed with end().
   • Context Loss: Validate context propagation in HTTP clients or queue workers.
   • Sampling: If using sampling, confirm your spans are included:

     $tracer->withSampler(new AlwaysSample());
     

3. Performance Bottlenecks:

   • High Cardinality: Avoid metrics with too many labels (e.g., user_id in counters).
   • Exporter Backpressure: Throttle flushes if the exporter is slow:

     app(Telemetry::class)->setFlushInterval(10); // Seconds
     

Tips

1. Start Small:

   • Instrument one critical path (e.g., a high-traffic API route or queue job) before scaling.

2. Use Laravel’s Observability:

   • Combine with Laravel Telescope or Scout APM for broader coverage:

     if (app()->environment('production')) {
         Telemetry::counter('api.requests')->increment();
     }
     

3. Custom Metric Names: