Opentelemetry Auto Class Laravel Package

Product Decisions This Supports

• Observability as a Core Feature: Automatically instrument critical business logic (e.g., OrderService, PaymentGateway) to reduce mean time to resolution (MTTR) for production issues. Aligns with SRE principles by providing automatic, low-effort tracing without manual instrumentation.
• Developer Experience (DX) Investment: Reduce cognitive load for backend engineers by eliminating boilerplate tracing code. Enables faster onboarding for new hires unfamiliar with OpenTelemetry.
• Performance Optimization Roadmap: Identify latency bottlenecks in high-traffic APIs (e.g., checkout flows, real-time notifications) by correlating spans with metrics (e.g., p99 response times).
• Compliance and Auditability: Auto-tag sensitive operations (e.g., User::updatePassword(), Admin::deleteRecord()) to meet GDPR, HIPAA, or SOC2 requirements with minimal engineering effort.
• Multi-Cloud/Hybrid Observability: Standardize tracing across AWS, GCP, and on-prem environments using OpenTelemetry’s vendor-agnostic exporters (e.g., Jaeger, Tempo, or Datadog).
• Cost-Effective Observability: Avoid proprietary tools (e.g., New Relic, Dynatrace) by leveraging open-source OTel with minimal operational overhead.
• Laravel-Specific Use Cases:
  • Middleware Tracing: Auto-instrument Laravel’s middleware pipeline (e.g., Authenticate, Validate) to trace request flows.
  • Queue/Job Observability: Track async workflows (e.g., SendWelcomeEmailJob) with spans for failed retries, processing time, and dependencies.
  • Database Query Analysis: Integrate with Laravel’s Eloquent or Query Builder to trace slow queries (e.g., #[Traceable] on repository methods).

When to Consider This Package

• Adopt if:
  • Your Laravel/PHP application has 5+ microservices or complex workflows requiring distributed tracing.
  • You’re migrating from manual logging to structured observability and need low-code instrumentation.
  • Your team prioritizes developer productivity over fine-grained control (e.g., custom sampling rules).
  • You’re using OpenTelemetry (or planning to) and want to reduce setup friction for PHP services.
  • Critical paths (e.g., payments, auth, data pipelines) require automatic audit trails for compliance.
  • You’re building event-driven systems (e.g., Kafka, RabbitMQ) where tracing spans across services is essential.
• Look elsewhere if:
  • Your app is monolithic with minimal external dependencies (manual tracing or Laravel Telescope may suffice).
  • You need dynamic sampling (e.g., trace only 1% of requests) or custom span attributes (this package uses attribute-based rules).
  • Your PHP version is <8.2 or lacks ext-opentelemetry support.
  • You’re constrained by legacy codebases where attributes or reflection aren’t feasible.
  • Your observability stack doesn’t support OpenTelemetry (e.g., vendor-specific tools like AWS X-Ray or AppDynamics).
  • You require real-time metrics (e.g., Prometheus) alongside tracing—consider spatie/laravel-monitoring or laravel-prometheus.

How to Pitch It (Stakeholders)

For Executives/Business Leaders: "This package lets us automatically track every critical operation in our Laravel apps—like a flight data recorder for our code—without writing a single line of tracing logic. For zero incremental cost, we’ll gain visibility into performance bottlenecks (e.g., slow payments, failed API calls) to reduce downtime and improve user experience. It’s a force-multiplier for our observability roadmap, aligning with industry standards like OpenTelemetry. Think of it as ‘set it and forget it’ debugging for our most complex workflows."

For Engineering/Tech Leads: *"With #[Traceable], we can annotate key methods (e.g., OrderService::process()) and instantly get distributed traces—no more context-switching to add startSpan() calls. It’s a 10x productivity boost for debugging latency issues in production. Works seamlessly with Laravel’s service container and OpenTelemetry’s exporters (Jaeger, Honeycomb, etc.). Tradeoffs:

• Minimal customization (e.g., no dynamic sampling), but ideal for ‘set it and forget it’ tracing.
• Requires ext-opentelemetry (PHP 8.2+), but we’re already using Laravel 9+.
• Potential overhead for high-frequency methods (mitigated by OTel’s sampling).* Proposal: Pilot on our checkout and payment services to validate impact on MTTR."*

For Developers: *"This package eliminates tracing boilerplate. Instead of manually wrapping methods in startSpan()/endSpan(), we just add #[Traceable] to a class. For example:

#[Traceable]
class PaymentService {
    public function charge(float $amount): void {
        // Automatically traced! No manual setup.
    }
}

Why it’s useful:

• Debugging: See exactly where time is spent in complex workflows (e.g., PaymentService::charge() → StripeAPI::call()).
• Performance: Identify slow database queries or external API calls without adding logs.
• Collaboration: Share traces with frontend teams to correlate backend latency with UI jank. How to start:

1. Add composer require eerzho/opentelemetry-auto-class.
2. Annotate critical classes (e.g., OrderService, AuthController).
3. Configure OTel to export to Jaeger/Honeycomb.
4. Profit."*

For SRE/DevOps: *"This integrates with our existing OpenTelemetry stack to provide automatic, framework-agnostic tracing for Laravel services. Key benefits:

• Reduced alert noise: Only trace business-critical methods (exclude health checks, getters).
• Context propagation: Spans automatically include method arguments (e.g., orderId, userId) for debugging.
• Compliance: Audit trails for sensitive operations (e.g., User::deleteAccount()) with minimal effort. Risks:
• Over-tracing of low-value methods (mitigate with exclude lists or OTel sampling).
• Potential conflicts with existing OTel instrumentation (e.g., Laravel’s HTTP middleware). Recommendation: Pilot in non-production first, then roll out to high-impact services like payments and auth."*