Weave Code
Api Laravel Package
open-telemetry/api
OpenTelemetry PHP API package providing the core interfaces and no-op implementations for tracing, metrics, and context propagation. Use it to instrument libraries and apps while remaining exporter/SDK agnostic and compatible with OpenTelemetry.
[READONLY] The API for OpenTelemetry PHP
Frequently asked questions about Api
- How do I integrate OpenTelemetry API with Laravel for distributed tracing?
- Use the `Tracer` abstraction to create spans in middleware, controllers, or jobs. For HTTP requests, inject a middleware like `TraceMiddleware` to auto-start spans. Laravel’s service container can bind the tracer globally via `AppServiceProvider`. Pair with an SDK (e.g., `open-telemetry/sdk`) to export traces to backends like Jaeger or Datadog.
- What Laravel versions support the OpenTelemetry API package?
- The package requires PHP 8.1+, so ensure your Laravel app (8.1+) aligns with this. It’s compatible with Laravel 9/10 and avoids version-specific dependencies, making it future-proof. Test thoroughly if using older Laravel versions with PHP 8.0 or below.
- Can I use this API without an OpenTelemetry SDK?
- Yes, the API defines interfaces only—no SDK dependencies. However, you’ll need an SDK (e.g., `open-telemetry/sdk`) to collect and export telemetry. The API enables instrumentation, while SDKs handle exporters (OTLP, Zipkin, etc.). Start with the API for vendor-neutral code, then add an SDK later.
- How do I instrument Laravel queues/jobs with OpenTelemetry?
- Wrap job execution in spans using `Span::withSpan()` or middleware. For example, in a job class, start a span before processing and end it afterward. Use `Span::setAttribute()` to add context like job IDs or payloads. This ensures async workflows appear in your traces.
- What’s the performance impact of OpenTelemetry in Laravel?
- Instrumentation adds minimal overhead (~1–5% latency). Excessive spans or metrics can degrade performance, so use sampling (e.g., `SpanProcessor` with probabilistic sampling). Configure sampling rates in your SDK to balance observability and cost.
- How do I propagate context between Laravel services/microservices?
- Use the API’s `Propagator` (e.g., `TraceContext`) to inject headers (e.g., `traceparent`) into HTTP requests or gRPC calls. Laravel’s HTTP client (Guzzle) or middleware can auto-extract context from incoming requests. This ensures cross-service tracing in distributed architectures.
- Are there Laravel-specific examples for metrics or logs?
- The API provides `Meter` for metrics (e.g., request latency) and `Logger` for structured logs. Example: Use `Meter::getMeter()->createCounter('http.requests')` to track API calls. For logs, integrate with Monolog via `Logger::getLogger()` and add OpenTelemetry attributes like `span_id`. Docs cover SDK-specific integrations.
- What exporters work best with Laravel’s OpenTelemetry setup?
- Popular choices include OTLP (OpenTelemetry Protocol) for cloud-native backends (e.g., Jaeger, Grafana), Zipkin for legacy systems, or console exporters for debugging. Configure the exporter in your SDK (e.g., `OtlpSpanExporter`) and ensure your monitoring tool supports the protocol. OTLP is recommended for modern stacks.
- How do I handle breaking changes if upgrading the OpenTelemetry API?
- Check the [OpenTelemetry PHP migration guide](https://github.com/open-telemetry/opentelemetry-php/blob/main/docs/migration.md) for deprecated interfaces (e.g., `InstrumentationInterface`). Refactor code incrementally—start by updating SDK bindings, then adjust instrumentation logic. Use semantic versioning to plan upgrades during maintenance windows.
- What alternatives exist for observability in Laravel if OpenTelemetry feels complex?
- Consider lighter alternatives like Laravel Telescope for debugging or Monolog for logs. For tracing, packages like `spatie/laravel-activitylog` offer simpler event tracking. However, OpenTelemetry excels in distributed systems with multi-backend support (e.g., Prometheus + Jaeger). Start small with critical paths before full adoption.
Weaver
How can I help you explore Laravel packages today?