Telemetry Laravel Package

Getting Started

Start by installing the package via Composer:

composer require spiral/telemetry  

Then register the service provider in your Spiral application’s config/app.php (typically in the providers array):

Spiral\Telemetry\TelemetryProvider::class,  

Minimal setup requires no additional configuration — traces will be generated for HTTP requests, background jobs, and service calls by default. Verify functionality by triggering a request and checking the output (default: stderr or configured sink).

Implementation Patterns

• Request Tracing: Out-of-the-box integration adds spans for incoming HTTP requests, including route, status, and latency. Use Telemetry::span() to add custom spans:

  $span = Telemetry::span('user.login');  
  try {  
      // login logic  
      $span->setAttributes(['user_id' => $user->id]);  
  } finally {  
      $span->end();  
  }  
  

• Background Jobs: Automatically traces jobs dispatched via Spiral’s QueueInterface. To trace custom logic inside jobs, wrap in spans as above.
• Extending Providers: Implement SpanModifierInterface to inject context (e.g., user ID, tenant) into every span globally. Register modifiers in config/telemetry.php.

Gotchas and Tips

• No Default Exporter: This package only generates trace data — it does not ship traces to APM tools. You must implement a sink (e.g., OpenTelemetry collector) by registering a custom Spiral\Telemetry\ExporterInterface implementation.
• Span Naming Matters: Avoid dynamic strings in span names (e.g., user.$id). Use static semantic names like user.login to ensure effective aggregation and filtering.
• Memory Leaks in Long-Running Processes: In CLI workers, ensure every span() call is paired with end() — unended spans may persist in memory across iterations. Use try/finally blocks or lazy span resolution where possible.
• Config Overrides: Override defaults in config/telemetry.php — e.g., enabled, sampling, and exporter class — to tune behavior without code changes.