Transport Grpc Laravel Package

Product Decisions This Supports

• Observability architecture: build vs. buy, and the exit clause. Standardizing on OpenTelemetry PHP means instrumenting against an open wire format rather than embedding an APM vendor's agent. This package — the gRPC transport — is the interchangeable "last mile" of that decision. The strategic value is not the transport itself; it's that the APM backend becomes a swappable vendor choice rather than a multi-year architectural commitment.
• Transport standardization (gRPC vs. OTLP/HTTP). The real decision this package forces is how telemetry leaves the app: gRPC to your own Collector, or HTTP/protobuf. That choice ripples into base container images, firewall rules (port 4317 vs. 4318), platform-team runbooks, and serverless viability. It is an infrastructure decision disguised as a dependency.
• Roadmap sequencing for instrumentation. Choosing this stack requires an explicit answer to "what do we instrument first?" — HTTP requests and queue jobs, then Eloquent/Redis/HTTP-client spans, then business spans (checkout, onboarding, sync jobs). That ordering is a roadmap artifact, not just an engineering backlog.
• SLOs, error budgets, and reliable canary releases. Cross-service traces are the prerequisite for defensible latency/error SLOs and for judging a canary on p95 per route/version rather than aggregate error rate. Release gating quality is directly downstream of this pipeline being in place.
• Cost and spend modeling. With an OTel Collector in front, sampling, tail-based filtering, and tiering become Collector config rather than vendor contract renegotiation. Observability spend turns into a tunable line item — a meaningful budget lever at scale.
• Vendor consolidation / multi-language pipeline. Once more than one deployable exists (API + worker + scheduler, or multiple services in mixed languages), speaking the same OTLP protocol as the Go/Node/Python services is what makes a unified pipeline possible. This package is the PHP side of that convergence.
• APM migration path. It enables running a proprietary agent and OTel in parallel during cutover, de-risking the switch rather than making it a flag day.

When to Consider This Package

Adopt when several of the following hold:

• You have already committed to open-telemetry/sdk + open-telemetry/exporter-otlp and specifically need gRPC — because your Collector or a vendor's OTLP endpoint is gRPC-only, or span volume is high enough that protobuf-over-HTTP framing overhead is measurable.
• Your platform team owns the container build and can bake ext-grpc (a compiled PECL extension) into every runtime: php-fpm images, Octane/Swoole workers, Horizon containers, CI runners. This is the single biggest adoption gate. If you cannot ship the extension, this package is unavailable — not optional.
• You operate (or will operate) an OTel Collector, so batching, retries, tail sampling, and fan-out live outside the request lifecycle and your app is not the reliability-critical path for telemetry.
• You need vendor portability, or you're consolidating observability across services/languages onto one pipeline.
• You can pin the transport and SDK to the same monorepo release train. Version skew between them is the most common failure mode.

Look elsewhere when:

• You need request-level metrics and slow-query visibility in one Laravel app — Laravel Pulse gets you there at near-zero operational cost.
• You want deep, zero-instrumentation Laravel insight (queries, jobs, mail, cache, exceptions) out of the box — Telescope in dev, Nightwatch or a vendor agent in prod. OTel gives you a standard, not Laravel ergonomics; you will own the framework-level instrumentation.
• There is no Collector and no plan for one. Pointing an app directly at a vendor endpoint over gRPC makes the app the reliability-critical path for its own telemetry — a bad trade.
• Target runtimes include serverless (Vapor/Lambda) or managed PHP hosts where adding a native extension is impractical.
• Your primary need is log aggregation and error tracking rather than tracing; OTel logs in PHP are less mature than tracing, and dedicated tools are better value.
• Nobody owns observability as a discipline — a standard without an owner becomes unused SDK code and a dependency-update chore.

Two caveats worth stating plainly: this is a read-only subtree split of the opentelemetry-php monorepo, so the low star count and zero listed dependents reflect packaging mechanics, not adoption or health — judge it on upstream release cadence and issues. And it has a hard native dependency with no pure-PHP fallback; ext-grpc historically lags new PHP minor releases, which can block a Laravel upgrade.

How to Pitch It (Stakeholders)

Executive summary. We can instrument our Laravel services with OpenTelemetry — an open, vendor-neutral standard — instead of embedding a specific APM vendor's agent in our codebase. That converts observability from a multi-year vendor commitment into a configurable pipeline: the app emits standard telemetry to a Collector we control, and we choose — and can change — the backend that stores it. This package is the small, single-purpose gRPC transport that carries that telemetry; it is maintained upstream as part of the official OpenTelemetry PHP SDK.

Business value. (1) Negotiating leverage — backend pricing becomes contestable because switching costs fall to a Collector config change. (2) Reliability foundation — cross-service traces are the prerequisite for SLOs, error budgets, and trustworthy canary gating. (3) Faster incident resolution — one trace ID spanning web, queue, and downstream calls replaces manual log correlation. (4) No license cost — spend is engineering time plus backend, not a per-host agent fee.

For engineering. The code cost is low; the infrastructure cost is real and mostly upfront: adding ext-grpc to every base image, running and operating an OTel Collector (or using a managed one), and writing Laravel-specific instrumentation the ecosystem doesn't hand us. Budget it as a platform-team initiative, not a ticket. Recommended sequence: stand up the Collector and prove it end to end with the HTTP/protobuf exporter (no compiled extension required); instrument HTTP requests and queue jobs first; measure Collector ingest cost at realistic sampling rates; only then evaluate swapping to this gRPC transport, behind an env flag and run in parallel against a second Collector pipeline for one release cycle before cutting over. Pin SDK and transport versions together, and treat upgrades as scheduled maintenance with a named owner — including an explicit check that ext-grpc supports whatever PHP version the next Laravel upgrade requires.

Recommendation. Worth pursuing if we're consolidating on OpenTelemetry across more than one service, or expect to re-evaluate our APM vendor within two years. If we're a single Laravel app with no Collector and no observability owner, defer — Pulse plus a managed error tracker delivers most of the near-term value at a fraction of the operational cost, and this stack can be revisited when a second service appears. Either way, treat the gRPC transport specifically as a performance optimization with a measured baseline, not the starting point.