Gen Otlp Protobuf Laravel Package

Technical Evaluation

Architecture Fit

• This package is a generated-artifact leaf dependency, not an integration surface. It contains the PHP protobuf classes for OTLP messages (ExportTraceServiceRequest, ResourceMetrics, etc.). In any sane Laravel architecture it is pulled in transitively by open-telemetry/exporter-otlp; no application code imports it directly.
• Layering to communicate to stakeholders: Laravel app → OpenTelemetry PHP SDK (API/SDK) → OTLP exporter → gen-otlp-protobuf → OTLP collector → backend (Tempo/Jaeger/Prometheus/vendor).
• Its architectural value is standardization, not capability: it is what makes the OTLP wire contract real in PHP. That matters for vendor neutrality and for portability of instrumentation across environments.
• It does not provide instrumentation, sampling, configuration, HTTP/gRPC transport, or batching. Those live in sibling packages (exporter-otlp, sdk, contrib). A TPM who scopes this package as "the observability solution" will under-resource the actual work by roughly an order of magnitude.

Integration Feasibility

• Feasibility is high because the integration is indirect. If the team adopts the OTel PHP SDK with an OTLP exporter, this package arrives as a locked, versioned dependency and requires zero engineering effort. Effort concentrates in SDK bootstrap, collector deployment, and backend selection.
• The one genuine engineering decision it forces is the protobuf runtime: google/protobuf (native, pure PHP, dependency-free) versus the pecl protobuf C extension. The README explicitly recommends the extension for production. That translates into a Docker base-image decision, a CI/PECL build step, and a platform-team commitment — not a composer require.
• gRPC is optional (grpc/grpc extension) and is a separate infrastructure conversation (proxy/firewall/HTTP2). HTTP/protobuf is the lower-friction default for most Laravel estates.

Technical Risk

• Misleading ecosystem signals. "Dependents: 0" and a 2023 last-release date reflect the git-subtree-split distribution model, not abandonment. The package is regenerated from the OpenTelemetry PHP monorepo (proto/otel), and versions track OTel spec releases. Any governance scorecard that gates on these two fields will produce a false negative — call this out before it enters a dependency-review board.
• Version skew. The protobuf classes and the SDK/exporter are released on different cadences. A pinned SDK with a floating protobuf package (or vice versa) is the most likely source of a confusing runtime failure. Pin both, together.
• Native extension drift. Images that lack ext-protobuf silently fall back to the pure-PHP implementation — functional, but a material CPU/latency cost at volume. This fails quietly, which is the worst kind of production risk.
• Generated code churn. Spec-driven regeneration can rename or restructure classes across minor versions. Any team writing directly against these classes (the "custom OTLP payload" use case) owns that migration cost forever.
• No commercial SLA. Apache-2.0, community-maintained, single-vendor-free. Support posture must be planned, not assumed.

Key Questions

1. Who is the owning team — platform/observability, or the application teams? (Recommendation: platform owns the dependency and the collector; apps own instrumentation.)
2. Are we consuming this only transitively via the SDK, or does a team intend to hand-build OTLP payloads? The latter is a scope and maintenance decision, not a coding decision.
3. Do our production images ship ext-protobuf? If not, what is the acceptance rationale?
4. What is the pin-and-upgrade policy for the SDK + exporter + protobuf triple, and who runs it?
5. Is there an existing observability vendor under contract? This package is the technical lever for renegotiation and eventual exit — is that part of the business case?
6. What telemetry volume do we forecast at 12 months, and does that forecast change the gRPC-vs-HTTP or extension decision?
7. Which collector topology (self-hosted, sidecar, managed distro) and who operates it?

Integration Approach

Stack Fit

• Do not integrate this package into Laravel directly. The correct composer target is open-telemetry/exporter-otlp plus open-telemetry/sdk; gen-otlp-protobuf follows as a transitive pin. This is the single most important instruction to give the engineering team, and it is the one most likely to be violated by an enthusiastic first implementer.
• Laravel-native touchpoints are where effort actually lands: a service provider for SDK bootstrap, middleware for HTTP spans, queue/job event listeners, and Laravel's HTTP client or a gRPC client for export. All of that is SDK-level work.
• Configuration belongs in config/observability.php + .env (OTEL_* variables), with the exporter endpoint/headers managed as secrets. Do not scatter OTEL_ reads through the codebase.
• Dockerfile/CI impact: add pecl install protobuf (and enable it) to the runtime image; add a CI assertion that the extension is loaded in the built image. This is a platform-team deliverable, not an app-team one.
• Dependency hygiene: pin SDK, exporter, and protobuf packages to aligned versions in composer.json; exclude the OTel group from blanket Renovate/Dependabot automerge and route those PRs to the owning team.

Migration Path

1. Decide, don't build (1–2 weeks). Confirm backend/collector target, runtime decision (native vs PECL), and ownership. Output: a one-page ADR and a named owner. This is the cheapest phase and prevents the most rework.
2. Pin and verify (1 week). Add the exporter + SDK, confirm gen-otlp-protobuf resolves as a transitive dependency at the expected version, and confirm ext-protobuf is present in a built image. Exit criterion: composer show output matches the ADR.
3. PoC on one service (2–3 weeks). Single Laravel service, local or staging collector, one request path instrumented. Validate end-to-end data in the backend UI. Exit criterion: a trace visible with correct service/resource attributes.
4. Widen instrumentation (4–8 weeks). Queues/jobs, scheduled commands, outbound HTTP. Set sampling and redaction policy before fan-out, not after.
5. Fleet rollout (per service). Template the service provider and middleware; make adoption a checklist rather than a project.
6. Decommission legacy. Retire the prior agent/APM only after a parallel-run window with data-parity verification. Do not skip this — it's where the cost savings are realized.

Compatibility

• Framework-agnostic; no Laravel version constraint imposed by this package. PHP version floor is governed by the SDK package, not by the protobuf package — confirm against the SDK's composer.json, not this one.
• google/protobuf v4 is supported (see 1.2.1). The PECL extension installs alongside the native library and takes precedence automatically — meaning a single image can serve both paths if needed.
• Long-running queue workers and Octane are the compatibility edge cases; verify that the exporter's batching does not leak memory across job cycles before fleet rollout.

Sequencing note: the collector should be stood up before the first instrumented service ships, even in staging. Teams that instrument first and provision the collector later accumulate dead instrumentation and lose trust in the effort.

Operational Impact

Maintenance

• Structurally low-maintenance: regenerated code, no hand-written logic, no security surface of its own. The maintenance burden is version coordination, not code.
• Ownership should sit with platform/observability. It should not appear on any application team's on-call rotation or sprint backlog.
• Expect one coordinated upgrade per OTel spec release, budgeted as routine platform work. Treat the SDK + exporter + protobuf as a single upgrade unit.

Support

• Community-supported upstream, Apache-2.0, no vendor SLA. Mitigation: prefer a vendor-backed distribution of the collector (which absorbs most operational risk) while keeping the PHP side on upstream.
• Because the protocol is OTLP, the exit path from any backend is a collector config change, not a code change. That is the strategic asset to document and socialize.

Scaling

• The pure-PHP protobuf fallback is the primary scaling cliff. Recommendation: make ext-protobuf a production image requirement and enforce it in CI, not a suggestion in a README.
• Volume scales with request count × workers × span count, and Laravel's queue workers multiply this quietly. Capacity-plan against queue concurrency, not just HTTP RPS.
• Batch and export configuration (batch size, timeout, max queue size) is an operational tuning surface that belongs to the owning team, with documented defaults and a review trigger when traffic grows.

Failure Modes

• Silent telemetry loss — collector unreachable, exporter drops batches. Detectable only if you monitor the collector's received-vs-sent metrics. Make this a mandatory dashboard item.
• Silent performance regression — extension absent, pure-PHP serialization in the hot path. Detectable via a build-time assertion; do not rely on latency graphs to surface it.
• Blocking on saturation — exporter backpressure propagating into request latency. Requires an explicit decision on drop-vs-block and a non-zero drop policy.
• Version skew between SDK and protobuf classes — manifests as opaque serialization errors at export time, often only in one environment. Prevented by pinning, not by debugging.
• Memory growth in long-running workers — batching state accumulating across jobs under Octane or queue daemons.
• PII leakage into span attributes — not caused by this package, but this package is what ships it to the backend. Redaction policy must precede rollout.

Ramp-up

• Very low for application engineers: most will never touch gen-otlp-protobuf. Their ramp-up is on OpenTelemetry concepts (traces/spans/context propagation/sampling) and Laravel instrumentation points — budget for that, not for protobuf.
• Moderate for the platform engineer who owns the dependency: protobuf runtime management, image build changes, and version pinning.
• Highest for whoever operates the collector and backend: this is the real operational cost center of the initiative and should be resourced first, not last.
• Onboarding artifact: a short internal runbook covering "how to instrument a new service," "how to bump the OTel dependency set," and "where to look when traces disappear." Three pages, owned by platform, reviewed quarterly.