Exporter Zipkin Laravel Package

Product Decisions This Supports

• Observability Roadmap Expansion: Enables distributed tracing for Laravel applications, bridging the gap between logging (Laravel Log) and metrics (Laravel Telescope). Critical for teams adopting microservices, event-driven architectures, or hybrid cloud setups.
• Build vs. Buy Decision: Buy—avoids reinventing Zipkin exporter logic while leveraging OpenTelemetry’s standardized instrumentation. Reduces long-term maintenance costs compared to custom solutions (e.g., rolling your own HTTP exporter).
• Feature Prioritization:
  • Debugging & Performance: Top priority for teams using Laravel queues (Horizon), API gateways, or third-party integrations (e.g., Stripe, Payment Gateways).
  • Compliance & Standards: Aligns with OpenTelemetry’s vendor-neutral format, easing future migrations (e.g., switching from Zipkin to Jaeger or Honeycomb).
  • Cost Efficiency: Free, actively maintained (via OpenTelemetry PHP), and integrates with open-source tools (Grafana Tempo, Zipkin UI) without licensing fees.
• Use Cases:
  • Microservices Orchestration: Trace requests across Laravel services, queues, and external APIs (e.g., a Laravel app calling a Node.js service).
  • Legacy Modernization: Add observability to monolithic Laravel apps without rewrites, using OpenTelemetry’s auto-instrumentation.
  • SRE/DevOps Workflows: Correlate traces with Laravel Horizon jobs, metrics (Prometheus), and logs for incident root-cause analysis.
  • API Performance: Identify latency bottlenecks in Laravel APIs (e.g., slow database queries, external API calls).

When to Consider This Package

• Adopt if:

  • Your team uses OpenTelemetry PHP SDK (or plans to) and needs Zipkin compatibility for tracing.
  • You require distributed tracing for Laravel-specific workflows (e.g., queues, HTTP clients, or event listeners).
  • You’re already invested in Zipkin (or tools like Grafana Tempo) and want to avoid vendor lock-in.
  • Your PHP version is 8.1+ (drop-in support for older versions was removed in v1.1.0).
  • You need low-code integration with existing observability stacks (e.g., Prometheus + Grafana + Zipkin).

• Look elsewhere if:

  • You need real-time analytics (Zipkin is tracing-focused; consider OpenTelemetry’s metrics exporters or dedicated APM tools like Datadog).
  • Your stack is non-PHP (e.g., Node.js/Python; use native Zipkin exporters or OpenTelemetry’s other SDKs).
  • You require advanced sampling (OpenTelemetry’s SDK handles this; this package is purely an exporter).
  • You’re constrained by low-resource environments (HTTP-based exporter adds overhead; consider batch processing or lighter tools like AWS X-Ray).
  • Your team lacks observability maturity (start with Laravel Log or Telescope before adopting tracing).

How to Pitch It (Stakeholders)

For Executives:

*"This package enables end-to-end visibility into our Laravel applications by integrating OpenTelemetry with Zipkin, a standard for distributed tracing. Here’s why it’s a strategic move:

• Reduce Downtime: Cut mean time to resolution (MTTR) for production issues by 30–50% with structured tracing (industry benchmarks).
• Scale Confidently: Gain insights into microservices, API latency, and queue processing—critical for high-traffic Laravel apps.
• Future-Proof: Uses OpenTelemetry’s open standard, so we can switch tools (e.g., from Zipkin to Jaeger) without re-instrumenting.
• Cost-Effective: Free, open-source, and integrates with existing tools (Grafana, Prometheus) without proprietary costs.

Ask: Should we prioritize this for our next observability sprint alongside Laravel Telescope and Prometheus metrics?"

For Engineering/DevOps:

*"This is the missing piece to export OpenTelemetry traces to Zipkin in Laravel. Here’s the implementation plan and trade-offs:

Why Use It?

• Zero reinvention: Leverages OpenTelemetry’s SDK (already in use?) and adds Zipkin compatibility.
• Lightweight: HTTP-based with configurable timeouts (no blocking I/O).
• Interoperable: Works with Zipkin UI, Grafana Tempo, or custom dashboards.
• Future-proof: OpenTelemetry’s standard format means we can swap exporters later.

How to Implement (5 Steps):

1. Upgrade PHP to 8.1+ (required for this exporter).
2. Add to composer.json:

   composer require open-telemetry/exporter-zipkin
   

3. Configure in OpenTelemetry SDK:

   use OpenTelemetry\Contrib\Zipkin\Exporter\ZipkinExporter;
   
   $exporter = new ZipkinExporter('http://zipkin-server:9411/api/v2/spans');
   $provider->addSpanProcessor(new \OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor($exporter));
   

4. Instrument Laravel Core:
   • Auto-instrument HTTP requests (via middleware).
   • Add traces to queues (Horizon) and jobs.
5. Validate:
   • Check traces in Zipkin UI or Grafana Tempo.
   • Set up alerts for high-latency spans.

Trade-offs:

• ~50–100ms latency per trace (mitigate with batch processing).
• Requires a Zipkin collector (self-hosted or cloud; e.g., Grafana Tempo).
• PHP 8.1+ only (upgrade Laravel to 9+ if needed).

Next Steps:

• Align on Zipkin endpoint (e.g., Tempo, Lightstep).
• Instrument critical paths (APIs, queues, cron jobs).
• Set up SLOs (e.g., "95% of API calls <500ms")."*

For Developers:

*"This exporter lets us send Laravel traces to Zipkin with minimal code. Here’s how to get started quickly:

1. Install & Configure:

composer require open-telemetry/exporter-zipkin

// In your OpenTelemetry setup (e.g., bootstrap/app.php)
$exporter = new \OpenTelemetry\Contrib\Zipkin\Exporter\ZipkinExporter('http://zipkin:9411/api/v2/spans');
$provider->addSpanProcessor(new \OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessor($exporter));

2. Auto-Instrument Laravel:

• HTTP Requests: Use middleware to inject trace context.

  use OpenTelemetry\API\Trace\Span;
  
  public function handle($request, Closure $next) {
      $span = Span::getCurrent();
      $request->headers->set('X-B3-TraceId', $span->getTraceId());
      return $next($request);
  }
  

• Queues: Add traces to Horizon jobs.

  use OpenTelemetry\API\Trace\TracerInterface;
  
  class MyJob implements ShouldQueue {
      public function handle(TracerInterface $tracer) {
          $span = $tracer->spanBuilder('process-job')->startSpan();
          // Job logic
          $span->end();
      }
  }
  

3. View Traces:

• Open Zipkin UI (e.g., http://localhost:9411) or Grafana Tempo.
• Search by service name, HTTP route, or custom attributes.

Pro Tip:

• Use sampling (e.g., 1% of requests) to reduce volume:

  $processor = new \OpenTelemetry\SDK\Trace\Sampling\AlwaysOnSampler();
  // Or: new \OpenTelemetry\SDK\Trace\Sampling\ProbabilitySampler(0.01);
  ```"
  
  

For Security/Compliance Teams:

*"This exporter does not transmit sensitive data by default—traces include:

• Timestamps, spans, and attributes (e.g., http.method, db.query).
• No PII unless explicitly added (e.g., user_id in custom attributes).

Mitigations:

• Filter attributes before exporting:

  $exporter = new ZipkinExporter('http://zipkin:9411/api/v2/spans', [
      'filter' => function ($span) {
          unset($span['attributes']['password']);
          return $span;
      }
  ]);
  

• Use sampling (e.g., 1%)