Transport Grpc Laravel Package

Technical Evaluation

Architecture fit. open-telemetry/transport-grpc is a leaf dependency, not an architectural commitment — the commitment is to OpenTelemetry plus a Collector. It implements the SDK's transport contract and slots into the OTLP exporter to ship traces, metrics, and logs over OTLP/gRPC (default 4317). It has no Laravel coupling: no service provider, no config file, no container bindings. Configuration is entirely environment-driven (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL=grpc, headers, timeout), which means it survives Laravel major upgrades and can be toggled per environment without code changes. The architectural value is vendor-neutral OTLP egress with lower serialization/framing overhead than JSON, plus native Collector semantics (batching, retries, tail sampling, fan-out) that keep the app out of the reliability-critical path — provided a Collector exists.

Integration feasibility. Code effort is trivial: one Composer require plus a few env vars. Infrastructure effort is not. ext-grpc is a compiled PECL extension that must be present in every runtime that emits telemetry: php-fpm images, Octane/Swoole workers, Horizon containers, CI runners, and serverless runtimes (Vapor/Lambda requires a custom PHP layer). The binary decision for a TPM is whether the platform team can guarantee that across the whole runtime matrix. If the answer is "no" or "not everywhere," this package should be treated as unavailable for that workload rather than optional, and those workloads should run OTLP/HTTP. A split-transport estate is acceptable if it is a deliberate, documented decision rather than drift.

Technical risk. Four material risks:

1. Hard native dependency. No pure-PHP fallback. The extension historically lags new PHP minors, so this package can become the blocker on a PHP or Laravel upgrade — a schedule risk, not just a technical one.
2. Packaging optics. This is a READONLY subtree split of the opentelemetry-php monorepo. The 917 stars, 0 listed dependents, and 2023-12 split release date reflect publishing mechanics, not adoption or health. Issues, PRs, and security advisories route to the monorepo, so any tooling or due-diligence process that keys off this repo will produce a misleading signal. Judge it on the upstream monorepo's release cadence.
3. Protobuf version skew. google/protobuf has both a C extension and a pure-PHP implementation; mismatched paths between local, CI, and production are a known source of silent serialization failure — the worst failure class, because telemetry disappears without alerting anyone.
4. In-request-path latency. The exporter runs inside the request lifecycle. Without deliberate timeout and batch-processor settings, a slow or retrying Collector adds tail latency to user traffic.

Key questions.

• What is the runtime matrix (php-fpm, Octane/Swoole, Horizon, Vapor, Cloud Run), and can ext-grpc be baked into every image?
• Does network policy permit egress to the Collector on 4317, and who terminates TLS — Collector, sidecar, or mTLS with client certs?
• Are we process-per-request or long-lived workers? gRPC channel setup amortizes well on Octane; it is per-request overhead on php-fpm.
• What is the fail policy — fail-open (drop telemetry, protect latency) or fail-closed (retry)? This should be an explicit product decision with a named owner.
• Who owns the SDK + transport version pair, and how do we detect a PHP/extension incompatibility before it reaches production?
• Do we actually need gRPC, or does OTLP/HTTP meet throughput targets with materially less infrastructure risk?
• Do existing dependencies (Google Cloud SDKs, internal gRPC services) constrain grpc/grpc or google/protobuf versions?
• What sampling and retention budget justifies the incremental transport and extension complexity?

Integration Approach

Stack fit. Laravel 10/11/12 on PHP 8.2–8.4 is a supported target; the package composes cleanly with open-telemetry/sdk, open-telemetry/exporter-otlp, and the auto-instrumentation package. Friction is environmental, not architectural.

Migration path. Do not frame this as greenfield. If telemetry already flows over OTLP/HTTP, the swap is at the exporter construction site — instrumentation, span names, and semantic attributes are unchanged. Gate it behind OTEL_EXPORTER_OTLP_PROTOCOL and run both transports in parallel for one release cycle against separate Collector pipelines, comparing span completeness, p99 export latency, and drop rate before cutover. If no telemetry exists yet, start on HTTP/protobuf: it proves the Collector, the instrumentation, and the dashboards without the extension dependency, and gives a measured baseline that makes the gRPC decision evidence-based rather than aspirational.

Compatibility. Pin the transport and SDK to the same monorepo release train — they are versioned together and mismatched minors are the most commonly reported failure mode. Verify ext-grpc and ext-protobuf build flags (OpenSSL, zlib) match across local, CI, and production; a locally green suite has repeatedly masked production extension gaps. Audit existing packages for conflicting grpc/grpc and google/protobuf constraints before requiring this one, and check PHP support in the extension's own release notes independently of this package's composer.json.

Sequencing.

1. Stand up the Collector and confirm OTLP/HTTP ingestion; record baseline trace completeness and ingest cost.
2. Enumerate the runtime matrix and prove ext-grpc builds into every image (including Horizon and Vapor if present). This is the go/no-go gate.
3. Instrument HTTP requests and queue jobs first, with W3C context propagation across the queue boundary — the single highest-value capability, and the one logging cannot give you.
4. Canary one service on gRPC behind the env flag; compare against the HTTP pipeline for a full release cycle.
5. Cut over service by service, not big-bang.
6. Expand scope to Eloquent, Redis, and HTTP-client spans, then custom business spans (checkout, onboarding, sync jobs).
7. Publish SLO dashboards and wire trace-derived percentiles into canary/release gating.

Operational Impact

Maintenance. Low code churn, but not zero ongoing cost: the SDK + transport pair should be upgraded on a scheduled cadence (quarterly is realistic), and every PHP minor upgrade forces an extension rebuild and validation pass. Assign a named owner — an unowned OTel installation decays into stale dependencies and unused SDK code. Treat the pair as a single upgrade unit in the backlog.

Support. Apache-2.0, no license cost and no vendor SLA. Support is community-based via the upstream monorepo and OpenTelemetry channels. Internal runbooks are therefore mandatory: how to verify the extension is loaded, how to validate the Collector endpoint and TLS chain, how to confirm spans are arriving, and how to roll back to HTTP. Because the split repo carries no issue history, engineers must be pointed at the monorepo explicitly or they will file bugs into a dead tracker.

Scaling. Batch at the SDK and again at the Collector; sample head-based in the app and tail-based at the Collector so cost is a tunable line item. On Octane the gRPC channel amortizes well; on php-fpm budget for per-request connection setup and confirm it is not visible in p95. Watch Collector ingest volume at real sampling rates before expanding instrumentation scope — the cost curve is the constraint most likely to force a rethink.

Failure modes. Extension absent at runtime (fatal or class-not-found — mitigate with a startup assertion and a deploy-time smoke check); Collector unreachable (dropped spans if fail-open, request latency if fail-closed with retries); TLS certificate expiry; protobuf implementation mismatch (silent drops or malformed payloads — the hardest to detect, so alert on export error rate and span volume, not just app errors); SDK/transport version skew (interface errors after a partial upgrade); unbounded batch queue in long-lived workers causing memory growth; egress firewall blocking 4317 discovered only in production.

Ramp-up. Realistic budget: one platform engineer for one to two sprints to stand up the Collector, build the extension into base images, and write the runbook; application engineers roughly a week each to instrument their service and review span quality; the wider team needs a short walkthrough on trace-driven debugging or the data goes unused. Expect four to six weeks from kickoff to the first defensible latency/error SLOs on a single service. Adopt this transport now if a Collector is already mandated and ext-grpc is a solved image problem; otherwise ship HTTP/protobuf first and revisit gRPC when volume or Collector requirements make the overhead savings measurable.