Api Laravel Package

Product Decisions This Supports

• Observability standard vs. vendor SDK: open-telemetry/api is the vendor-neutral contract layer of OpenTelemetry PHP — traces, metrics, logs, baggage, context propagation, and semantic conventions expressed as interfaces (plus a no-op implementation). Choosing it is a decision to instrument our code against an open standard rather than a proprietary APM agent, which keeps backend choice (Datadog, New Relic, Honeycomb, Grafana Tempo, Elastic, self-hosted Collector) a reversible, procurement-level decision instead of a rewrite-level one.
• Build vs. buy for instrumentation: the API layer is "buy/adopt for free" and the SDK/exporter is the replaceable part. We can accept the Apache-2.0 package as a dependency and defer the paid backend decision until we have telemetry volume data — a useful staging decision for roadmap sequencing.
• Roadmap enabler for distributed tracing: this package underpins cross-service trace context (W3C Trace Context and Baggage propagation, including size/entry caps in 1.10.0), span links, span suppression, and LocalRootSpan. That is what makes latency attribution across PHP services and queues feasible as a roadmap item rather than a research spike.
• Internal platform / shared library strategy: first-party Composer packages should depend on the API only, so consuming applications can inject the SDK and exporter. This gives us a clean library-vs-application boundary and avoids forcing a telemetry implementation on downstream teams.
• No-op safety and cost control: instrumentation compiled against the API is inert (no-op) when no SDK is registered. That supports shipping instrumentation into dev/test and lower environments now, and gating real export on a feature flag / environment configuration — a cost and privacy decision as much as a technical one.
• SLI/SLO and error-budget reporting: metrics instruments (counters, histograms, gauges, observable/multi-instrument callbacks) and log-record builders let us define user-facing SLIs in code rather than in a dashboard tool, so reliability targets can be versioned alongside features.
• Vendor migration de-risking: teams currently on a proprietary PHP agent can migrate incrementally — add the API contract and instrumentation, run dual-export, then cut the old agent.

When to Consider This Package

Consider adopting when:

• We are standardizing observability across polyglot services and need PHP to emit into the same OTLP pipeline (OpenTelemetry Collector) as Go/Node/JVM services.
• We maintain reusable Laravel/PHP packages or a shared internal framework and want them to emit telemetry without hard-depending on a backend or SDK — the correct place for open-telemetry/api.
• We want to defer or replace the observability vendor without touching application code.
• We need standards-compliant distributed trace propagation across HTTP, queue workers, and scheduled jobs (W3C Trace Context, Baggage).
• We need instrumentation to be a no-op in local/CI environments for performance and cost reasons.
• We are building internal auto-instrumentation or framework hooks; the package exposes hook manager and auto-instrumentation registration plus configuration providers (file/env-based since 1.4.0).

Look elsewhere / deprioritize when:

• The goal is "APM in a Laravel app by Friday." This package alone delivers zero visible value — it is an interface library. A usable stack requires open-telemetry/sdk, an exporter (e.g. exporter-otlp), and Laravel/PSR-15 auto-instrumentation, plus a Collector or OTLP-capable backend. Budget for that bundle, not this package.
• We need deep runtime profiling (memory flame graphs, line-level traces) — a managed APM agent is stronger today.
• We have no telemetry backend or Collector operated by anyone; the operational ownership cost exceeds the benefit at our current scale.
• The team is small and vendor auto-instrumentation (one-line agent install) already covers the need; standardizing on OTel adds integration work with no near-term payoff.
• We require long-term support guarantees and a single accountable vendor — this is a community-governed read-only subtree split of the OpenTelemetry PHP monorepo; support comes from the community and the spec, not a contract.
• Our runtime is old: PHP 8.0 and 7.4 support were dropped in the 1.1.0 line — verify our minimum PHP version before committing.

Adoption caveats to validate before committing:

• Maturity signals are moderate (stars ~917, score ~39, opportunity ~76, dependents: 0). Zero direct dependents understates real usage — most consumers pull it transitively via the SDK — but it does mean we must verify the Laravel instrumentation ecosystem ourselves rather than assume it.
• The metadata's "last release 2023-09-07" conflicts with the release notes present up to 1.10.0. Treat the date as stale/incorrect and re-verify the actual release cadence and changelog freshness before pinning, since active maintenance is a core adoption criterion.
• Pin to the 1.x series with a Composer constraint; note the API has had deprecations (e.g. InstrumentationInterface, ConfigurationResolver deprecated in 1.9.0, event logger in 1.2.0) — expect some churn in instrumentation code and plan for it.

How to Pitch It (Stakeholders)

For executives — one paragraph: OpenTelemetry is the industry-standard, vendor-neutral way to collect traces, metrics, and logs, and open-telemetry/api is the PHP contract for it: Apache-2.0 licensed, no cost, no lock-in. Adopting it means the instrumentation we write is a durable asset — we can switch observability vendors or bring telemetry in-house without rewriting application code, which converts a large, hard-to-reverse procurement decision into a routine one. It is the plumbing, not the product: it costs us little to standardize on now and it preserves our options and bargaining position later.

For engineering — the honest summary: This is the API/abstraction layer only — interfaces plus a no-op implementation. It is what our code and our shared packages should compile against; it does nothing on its own. A working setup is a three-part bundle: open-telemetry/api (what we code against), open-telemetry/sdk (the implementation, added once at the app's composition root), and an exporter plus Laravel/PSR-15 auto-instrumentation (what actually ships data to a Collector). Because uninstrumented code paths resolve to no-ops, it is safe in dev, test, and CI, and we can gate real export by environment. It supports traces with span links and span suppression, metrics including histograms/gauges/observable callbacks, log records with trace correlation, and W3C Trace Context and Baggage propagation with enforced size and entry caps. Engineering rules of thumb: applications require the SDK and exporter; libraries require only the API. Note that PHP 7.4 and 8.0 are no longer supported in the current line, so confirm our runtime baseline; and verify the live release cadence before pinning, since the package metadata's release date appears stale relative to the published 1.10.0 notes.

For the sponsor conversation — the ask: Approve a small, time-boxed spike: wire the API + SDK + OTLP exporter into one representative Laravel service behind a feature flag, emit a handful of spans and an SLI metric, and confirm it flows through a Collector to a backend of our choosing. Success criterion is a working end-to-end trace for one user journey and a defensible per-GB telemetry cost estimate — after which we decide on backend and rollout scope with real data instead of projections.