- How do I add automatic tracing to Laravel services like OrderService or PaymentProcessor?
- Annotate your class with `#[Traceable]` and register it via `AttributeScanner` and `ClassInstrumentation`. For Laravel, use the dedicated package `eerzho/opentelemetry-auto-class-laravel` to auto-discover annotated classes without manual scanning. Example: `#[Traceable] class OrderService { ... }` traces all public methods automatically.
- Does this package work with Laravel 9+ or only newer versions?
- The package requires PHP 8.2+ and is fully compatible with Laravel 9+ (LTS). Older Laravel versions (8.x) may need polyfills or adjustments, but the core functionality aligns with modern Laravel’s service container and dependency injection patterns.
- Can I exclude specific methods from tracing, like health checks or getters?
- Yes, use the `exclude` parameter in the `#[Traceable]` attribute. For example, `#[Traceable(exclude: ['healthCheck', 'getVersion'])]` will skip those methods while tracing the rest. This is useful for high-frequency or non-critical methods.
- Will this interfere with Laravel’s middleware or queue/job tracing?
- No, the package integrates seamlessly with Laravel’s middleware stack and queue system. Annotate job classes (e.g., `SendWelcomeEmailJob`) or service methods to trace async workflows. For HTTP requests, combine it with Laravel’s middleware or use the `opentelemetry-auto-class-laravel` integration for auto-discovery.
- What’s the performance impact of tracing methods with #[Traceable]?
- The overhead is minimal—typically 1–3% latency per traced method—thanks to OpenTelemetry’s zero-code instrumentation via `ext-opentelemetry`. For high-throughput APIs (e.g., payment processing), use OTel’s sampling processors to limit trace volume (e.g., sample 10% of critical methods).
- How do I handle sensitive data in traced method arguments, like passwords or tokens?
- Use the `#[Arguments]` attribute to exclude sensitive arguments or map them to custom names. For example, `#[Arguments(exclude: ['password'])]` prevents sensitive data from appearing in traces. This works alongside `#[Traceable]` to ensure compliance with security best practices.
- Does this package support tracing Eloquent queries or database interactions?
- Direct Eloquent query tracing isn’t built-in, but you can annotate repository methods (e.g., `#[Traceable] public function findByEmail()`) to trace business logic around queries. For raw SQL or query caching conflicts, avoid annotating methods that interact directly with the database or use middleware-based tracing instead.
- What backends (Jaeger, Datadog, New Relic) can consume traces from this package?
- The package generates OpenTelemetry-compatible spans, so it works with any OTel-supported backend. Configure the OTel PHP SDK’s exporter (e.g., `OtlpHttpSpanExporter` for Jaeger or `DatadogExporter`) to send traces to your preferred observability platform. Some backends may require custom processors or sampling rules.
- How do I integrate this with existing Laravel OpenTelemetry setups like spatie/laravel-otel?
- Avoid duplicate instrumentation by aligning configurations. Use `opentelemetry-auto-class-laravel` for auto-discovery and ensure the OTel PHP SDK is initialized once. If conflicts arise, prioritize one instrumentation method (e.g., use `#[Traceable]` for services and middleware for HTTP requests) and disable redundant auto-instrumentation.
- Are there any limitations with Laravel facades or magic methods (e.g., HasMany)?
- Facades or magic methods (e.g., `User::find()`) won’t be traceable via `#[Traceable]` because they bypass direct class instantiation. Workaround: Annotate the underlying class (e.g., `UserModel`) instead. For complex cases, consider manual span creation or middleware-based tracing for facade interactions.