Exporter Zipkin Laravel Package

Technical Evaluation

Architecture Fit

• Observability Strategy Alignment: The package enables distributed tracing for Laravel applications, complementing existing logging/metrics by providing end-to-end request visibility. This is critical for microservices, async workflows (e.g., Laravel queues), and debugging latency issues.
• OpenTelemetry Ecosystem: Leverages the OpenTelemetry PHP SDK, which is already a standard for modern PHP observability. This ensures future-proofing (e.g., switching exporters without re-instrumenting).
• Zipkin Compatibility: Bridges Laravel’s PHP stack with Zipkin’s UI/analysis tools, enabling teams already using Zipkin (or tools like Grafana Tempo) to avoid vendor lock-in.
• Laravel-Specific Gaps: While the package is generic, Laravel’s event-driven architecture (queues, jobs, HTTP middleware) can benefit from custom instrumentation (e.g., auto-tagging queue jobs with trace IDs).

Integration Feasibility

• Modular Design: The exporter is plug-and-play with OpenTelemetry’s SpanProcessor interface, requiring minimal Laravel code changes.
• HTTP Transport: Uses async HTTP clients (via php-http/async-client-implementation), which aligns with Laravel’s non-blocking I/O patterns (e.g., queues, async jobs).
• Configuration Flexibility: Supports:
  • Custom Zipkin endpoints (e.g., self-hosted, cloud-based).
  • Batch processing (reduces export volume).
  • Timeouts (mitigates slow Zipkin servers).
• Laravel Middleware: Can integrate with Laravel’s HTTP middleware to inject/extract trace context (e.g., X-B3-TraceId headers).

Technical Risk

Key Questions

1. Zipkin Infrastructure:
   • Is there an existing Zipkin-compatible collector (e.g., Jaeger, Grafana Tempo)?
   • What are the SLA requirements for trace export (latency, reliability)?
2. Sampling Strategy:
   • Should traces be sampled (e.g., 5% of requests) to reduce volume?
   • How will sampling be configured (head-based, tail-based)?
3. Laravel Integration Depth:
   • Should all HTTP requests, queue jobs, and commands be traced?
   • Are there custom Laravel events that need trace correlation?
4. Error Handling:
   • How should failed exports be logged/monitored?
   • Should traces be buffered during Zipkin outages?
5. Cost vs. Alternatives:
   • Is Zipkin the best fit (vs. OTLP exporters, Datadog, New Relic)?
   • Are there budget constraints for self-hosting Zipkin?

Integration Approach

Stack Fit

• OpenTelemetry PHP SDK: The package is designed for OpenTelemetry’s PHP SDK, which is already a mature stack in Laravel via:
  • telemetryphp/telemetry (auto-instrumentation).
  • Manual SDK setup (e.g., open-telemetry/sdk).
• HTTP Clients: Laravel’s Guzzle or Symfony HTTP Client can be reused for Zipkin exports if async transport is configured.
• Logging Correlation: Traces can be correlated with Laravel logs via:
  • X-B3-TraceId headers in HTTP requests.
  • Custom log formatters (e.g., Monolog processors).
• Async Workflows: Integrates with Laravel’s queues/jobs by:
  • Auto-instrumenting Illuminate\Bus\Queueable.
  • Injecting trace context into dispatched jobs.

Migration Path

Example Implementation:

// composer.json
"require": {
    "open-telemetry/sdk": "^1.0",
    "open-telemetry/exporter-zipkin": "^1.2",
    "telemetryphp/telemetry": "^1.0" // Optional: Auto-instrumentation
},

// config/telemetry.php
'exporters' => [
    \OpenTelemetry\Contrib\Zipkin\Exporter\ZipkinExporter::class => [
        'endpoint' => env('ZIPKIN_ENDPOINT', 'http://zipkin:9411/api/v2/spans'),
        'timeout' => 2.0,
        'batch' => [
            'size' => 50,
            'interval' => 1000, // ms
        ],
    ],
],

// app/Providers/AppServiceProvider.php
use OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessor;
use OpenTelemetry\Contrib\Zipkin\Exporter\ZipkinExporter;

public function boot()
{
    $exporter = new ZipkinExporter(config('telemetry.exporters.zipkin'));
    $provider = \OpenTelemetry\SDK\Trace\Provider::getProvider();
    $provider->addSpanProcessor(new BatchSpanProcessor($exporter));
}

Compatibility

Sequencing

1. Phase 1: Instrumentation
   • Add OpenTelemetry SDK and auto-instrument Laravel’s HTTP layer (routes, middleware).
   • Example: Trace all incoming requests with OpenTelemetry\API\Trace\TracerInterface.
2. Phase 2: Zipkin Exporter
   • Configure the Zipkin exporter with batch settings and timeout.
   • Test with a local Zipkin instance (e.g., Docker).
3. Phase 3: Async Workflows
   • Instrument queues/jobs to include trace context.
   • Example: Use telemetryphp/telemetry for queue auto-instrumentation.
4. Phase 4: Middleware Integration
   • Add middleware to inject/extract trace headers (X-B3-TraceId, X-B3-SpanId).
   • Example:

     // app/Http/Middleware/TraceContext.php
     public function handle($request, Closure $next)
     {
         $traceContext = \OpenTelemetry\API\Trace\Propagation\TextMapPropagator::getInstance()
             ->extract(\OpenTelemetry\API\GlobalPropagation::get(), $request->headerBag);
         // ... inject into current span
         return $next($request);
     }
     

5. Phase 5: Validation
   • Verify traces appear in Zipkin for:
     • API endpoints.
     • Queue jobs.
     • Background commands.
   • Check for missing attributes or correlation gaps.

Operational Impact

Maintenance