Exporter Otlp Laravel Package

Technical Evaluation

Architecture fit. The exporter is a leaf, pluggable dependency, not a framework component. It implements the SDK's exporter interfaces (SpanExporter, PushMetricExporter, LogRecordExporter) and is deliberately transport-agnostic: you construct a transport via OtlpHttpTransportFactory (PSR-18 client, JSON or protobuf payloads) or install open-telemetry/transport-grpc for gRPC. In Laravel this maps cleanly onto a service provider that binds a transport singleton, wires the exporter into a TracerProvider, and exposes a middleware that starts/ends a root span per request. There is no first-party Laravel package — the exporter is one layer of a stack (API + SDK + exporter + protobuf runtime) you assemble yourself.

Integration feasibility. Straightforward at the code level (a few hours to a working prototype against a local collector), harder at the platform level. Two hard prerequisites dictate feasibility:

• Protobuf runtime. OTLP serialization requires a protobuf implementation. The pure-PHP google/protobuf package is explicitly documented as unsuitable for production performance; ext-protobuf (via pecl install protobuf) is the recommended path. That means image build changes and a hard dependency on a compileable extension across every runtime target: FPM, queue workers, Octane, and any serverless/managed platform.
• Transport choice. gRPC requires ext-grpc; HTTP/protobuf or HTTP/JSON works with curl. HTTP to a collector is the pragmatic default for PHP-FPM.

Technical risk.

• Repo metadata is misleading. This GitHub repo is a read-only subtree split mirror of the opentelemetry-php monorepo; the 917 stars, "0 dependents," and the stale 2023-09-07 release date are artifacts of the split, not signals of adoption or dormancy. The changelog runs to 1.4.0. Evaluate the monorepo and Packagist download counts instead, and re-verify the current release before pinning.
• Protobuf version churn is a recurring failure class. Releases 1.3.1 and 1.4.0 are both patches (and a revert) around google/protobuf / ext-protobuf version skew — including a TypeError in serializeToJsonString() when the native library and extension versions diverge. Expect this to bite during base-image upgrades.
• The exporter is in the request path. Misconfigured batching, timeouts, or retries can add latency to every request or silently drop telemetry. This is a hot-path dependency and must be treated as such in code review.
• No Laravel-native instrumentation. Auto-instrumentation of Eloquent queries, queue jobs, HTTP clients, and Redis is not provided; you write or adopt community middleware, and inherited maintenance risk with it.

Key questions. Which backend — a self-hosted OTel Collector or a vendor OTLP endpoint — and who owns it? Is ext-protobuf (and optionally ext-grpc) available in all deployment targets, including any Laravel Vapor/serverless path? Which SDK/API version is pinned, and is it stable for the signals we need? Is this greenfield or a replacement for an existing APM agent, and who owns the cutover? What is the sampling policy and the PII redaction policy for span attributes?

Integration Approach

Stack fit. Requires PHP 8.1+ (8.0 support was dropped in 1.1.0beta1). Compatible with Laravel 9/10/11 on Composer. Typical install: open-telemetry/sdk, open-telemetry/exporter-otlp, open-telemetry/gen-otlp-protobuf (or the C extension instead of the generated classes' native runtime), and open-telemetry/sem-conv for attribute naming. Budget for a custom OpenTelemetryServiceProvider and a TraceRequest middleware; without that glue the exporter does nothing.

Migration path. Incremental and reversible:

1. Stand up an OTel Collector (docker-compose locally, Helm/managed in staging) listening on :4318; confirm the OTLP receiver with a throwaway script.
2. Wire traces first, HTTP/JSON, one non-critical service, behind a config flag. JSON is easier to debug in the collector's logs.
3. Switch to HTTP/protobuf once volume justifies it; only adopt gRPC if you already run ext-grpc.
4. Add metrics, then logs — each signal has separate exporter wiring and separate sampling/retention concerns.
5. Only then retire any existing APM agent, keeping traces dual-shipped during the overlap.

Compatibility. OTLP 1.x is a stable, widely implemented wire spec, so collector and vendor compatibility is low-risk. Keep endpoint, headers, and timeout in OTEL_EXPORTER_OTLP_* environment variables (URL-encoded header values are supported since 1.0.4) so ops can repoint the pipeline without a code deploy. Pin the SDK and exporter to matching minor versions — they are released in lockstep from the monorepo.

Sequencing. Platform prerequisite (protobuf in base images) → collector deployed and validated → SDK + provider + middleware in one service → sampling and batch tuning → context propagation across queues and outbound HTTP → additional signals → dashboards, SLOs, and alerting on the pipeline itself. The dependency order matters: instrumentation before tuning, tuning before rollout, and rollout before you change on-call expectations.

Operational Impact

Maintenance. Low expected churn for a pinned version — this is a spec-driven, CNCF-backed project with disciplined semantic versioning and a stable 1.x line. The real maintenance load is environmental: base-image PHP upgrades that move the native protobuf library ahead of or behind ext-protobuf. Track the upstream changelog for exactly that class of patch. Note the split-repo consequence: issues and PRs must be filed against opentelemetry-php, not here, so your team needs to know the canonical upstream.

Support. Apache-2.0, community-supported, no vendor SLA. There is no commercial escalation path. Name an internal owner for the telemetry pipeline — otherwise a broken exporter becomes an unowned failure that silently degrades observability right when you need it.

Scaling. Export cost is per-request serialization inside the PHP process. Use a batch processor with tuned queue size, batch size, and export timeout, and sample aggressively at the head rather than trying to export everything. Two PHP-specific traps: in FPM, spans are lost unless you flush on shutdown, since there is no long-lived process to drain the buffer; under Octane or long-running queue workers, batch buffers persist across requests and must be reset, or they grow unboundedly and leak memory across jobs.

Failure modes to design for.

• Collector unreachable: exports fail; if failures are surfaced synchronously they add latency and log volume. Export must be non-blocking and failure must never fail a user request.
• Protobuf mismatch: serialization TypeError or deprecation noise after an image upgrade — the documented 1.3.1/1.4.0 pattern. Gate with a smoke test in CI that actually exports a span.
• Buffer growth under load: queue full plus slow collector means memory pressure and dropped or delayed spans. Alert on export failures and queue saturation, not just on missing traces.
• Data loss windows: fatal errors, worker kills, and deploy restarts drop in-flight buffers. Accept this explicitly or use a local collector sidecar.
• PII and cost: span attributes are free-form and easy to over-capture; unredacted user IDs, tokens, or query params create a compliance problem, and verbose attributes drive egress and storage cost. Enforce an attribute allowlist in middleware.

Ramp-up. Engineers need OpenTelemetry vocabulary — traces, spans, context propagation, sampling, resources, semantic conventions — before they write useful instrumentation; naive spans ("controller called") add cost without diagnostic value. Budget roughly a sprint for the first instrumented service, plus SRE time to run the collector and write runbooks for "telemetry pipeline degraded" and "application latency regressed after instrumentation." Treat the first service as a reference implementation and template the provider and middleware for the rest.