Api Laravel Package

Technical Evaluation

Architecture fit: open-telemetry/api is not a Laravel package or a complete telemetry implementation. It is the PHP OpenTelemetry API layer: interfaces, context/propagation contracts, semantic conventions, attributes, no-op defaults, clock abstractions, and instrumentation hooks. For Laravel, it fits as a transitive contract dependency behind open-telemetry/sdk, exporters, and auto-instrumentation. It is appropriate for custom business spans, request/job context propagation, and vendor-neutral instrumentation, but installing only open-telemetry/api will produce no telemetry. The TPM should treat it as the standard interface that application code compiles against, not as the observability product.

Integration feasibility: Composer-based integration is straightforward, and Apache-2.0 licensing keeps legal friction low. Laravel integration is feasible through a service provider, HTTP middleware, queue middleware, Guzzle/HTTP-client instrumentation, and OTLP export to an OpenTelemetry Collector. The API’s W3C trace-context and baggage support is the right foundation for distributed tracing across Laravel HTTP requests, queued jobs, scheduler tasks, and outbound calls. The releases show useful capabilities for this use case: stabilized LocalRootSpan, span suppression strategies, semconv generation, baggage size/entry caps, response propagator interfaces, and auto-instrumentation registration/hook management. However, the package is a read-only subtree split of the monorepo, so issue tracking, fixes, and contributions happen upstream.

Technical risk: The main risk is mistaking the API package for a turnkey Laravel observability solution. It has no exporter, no SDK configuration, no sampling implementation, no collector, and no backend. Without an SDK, the API’s no-op behavior means teams may believe telemetry is enabled when nothing is recorded. Version compatibility must be verified: releases dropped PHP 7.4 and 8.0, and later releases include PHP 8.4 fixes, so the supported PHP/Laravel matrix needs confirmation. The API surface has churn and deprecations: InstrumentationInterface, ConfigurationResolver, event logger, and earlier experimental APIs have been deprecated or removed. The metadata says last release “2023-09-07,” but release notes reference 1.10.0 and later changes, so release-date metadata should be treated as stale until verified on Packagist. “Dependents: 0” is not a reliable adoption signal for a subtree-split API package that is normally consumed transitively. Auto-instrumentation and hook-based approaches can also introduce runtime prerequisites and Octane/long-running-worker lifecycle concerns.

Key questions:

• Are we standardizing on OpenTelemetry/OTLP, or integrating with an existing APM that already has a Laravel agent?
• Which signals are in scope first: traces only, then metrics/logs, or all three?
• Which Laravel and PHP versions must be supported, including Octane, queue workers, scheduler, and PHP 8.4?
• Will we use auto-instrumentation, manual middleware/service-provider instrumentation, or a vendor Laravel package?
• Where will telemetry go: direct OTLP export, OpenTelemetry Collector, or vendor endpoint?
• What sampling, PII redaction, baggage limits, and data-residency rules are required?
• Who owns the SDK configuration, collector, dashboards, alerts, and on-call runbooks?
• Can we accept dependency on the upstream monorepo release cadence and community support model?

Integration Approach

Stack fit: The API package should be pinned as part of the OpenTelemetry dependency set, not adopted alone. A Laravel application should typically install the SDK, OTLP exporter, and any approved instrumentation packages, with open-telemetry/api pulled transitively. Application code can use API interfaces for custom spans, attributes, and context extraction/injection, while infrastructure configuration lives in a Laravel service provider and environment variables. The Collector should be the stable boundary so the application is not tightly coupled to a specific observability backend.

Migration path: Start with a single Laravel service and a Collector in the target environment. Add request middleware that creates or continues a root span, extracts W3C traceparent/baggage from inbound requests, records route/controller/status attributes, and captures exceptions. Add outbound HTTP and queue propagation once request tracing is stable. Compare traces against the existing APM or logs before expanding. Then roll out the same service-provider/package pattern across applications, using a shared internal Laravel telemetry package to avoid per-app drift.

Compatibility: Validate PHP/Laravel support against the exact API, SDK, exporter, and instrumentation versions. Confirm OTLP transport choice: HTTP/protobuf versus gRPC, and whether required PHP extensions are available in Laravel runtime images. For Laravel Octane or long-running workers, verify context cleanup between requests/jobs. For queues, confirm that trace headers survive serialization and that failed/retried jobs do not create duplicate or orphaned spans. For logging, decide whether to bridge Laravel logs into OTel logs or keep logs in the existing stack initially.

Sequencing:

1. Inventory existing observability, backends, SLOs, and Laravel runtime variants.
2. Stand up an OpenTelemetry Collector and choose sampling/redaction policy.
3. Add SDK/exporter configuration behind a feature flag in one Laravel app.
4. Instrument inbound HTTP requests and exceptions with manual middleware.
5. Instrument outbound HTTP, queue dispatch/processing, scheduler, and console commands.
6. Add custom business spans and semantic-convention attributes for critical flows.
7. Evaluate auto-instrumentation only after manual instrumentation proves stable.
8. Add metrics/logs selectively, then dashboards, alerts, and runbooks.
9. Roll out via the internal Laravel package and track adoption, cost, and telemetry quality.

Operational Impact

Maintenance: The API package itself is low-maintenance from an application perspective because it is an interface layer, but the surrounding OpenTelemetry PHP SDK, exporters, instrumentation packages, and Collector require active version management. Pin versions, use dependency automation, and test upgrades in a staging Laravel app. Because the repository is a read-only split, upstream fixes must be tracked in the monorepo. Avoid depending on deprecated API surfaces such as ConfigurationResolver, InstrumentationInterface, and the event logger. Expect ongoing semconv updates; route, HTTP, database, and messaging attribute names should be standardized internally.

Support: Support is community-driven OpenTelemetry PHP, not a commercial Laravel APM vendor. The TPM should establish an internal ownership model: platform team owns the SDK/collector golden path, application teams own service-level instrumentation quality, and observability/on-call owns dashboards and alerts. Document the “no-op trap”: if SDK configuration is missing or broken, the API may silently produce no spans. Provide a golden-path Laravel package, configuration examples, and a telemetry validation checklist.

Scaling: Scaling risk is less about the API package and more about telemetry volume, cardinality, and export behavior. Use head sampling in the SDK and collector-level tail sampling where appropriate. Avoid high-cardinality attributes such as user ID, request ID, or raw URL on metrics. Batch exports and monitor exporter queue/drop behavior. For Laravel Octane, ensure spans and context are cleaned between requests to avoid memory growth and cross-request contamination. For queue-heavy systems, propagate context deliberately and avoid creating new root spans on every retry unless intended.

Failure modes: Common failure modes include installing the API without an SDK, exporter endpoint or credential misconfiguration, Collector unavailability causing dropped telemetry, lost context across queues, duplicate spans from overlapping auto-instrumentation and manual middleware, oversized baggage or attributes, PII leakage into span attributes, and memory/context leaks in long-running workers. The 1.10.0 baggage size and entry-count caps help limit abuse, but application-level redaction is still required. Telemetry export must never block request handling; use asynchronous/batched export and fail open from the application’s perspective.

Ramp-up: Teams need education on OpenTelemetry concepts: traces, spans, context, propagation, sampling, resources, semantic conventions, and OTLP. Laravel developers can adopt manual middleware and service-provider patterns quickly, but auto-instrumentation and Collector operations require deeper platform knowledge. Plan a short enablement cycle, a reference implementation, and instrumentation review during the first few services. The TPM should measure ramp-up by time-to-first-useful-trace, percentage of critical paths instrumented, context-propagation correctness across HTTP/queues, and reduction in mean time to diagnose incidents.