Instrumentation Bundle Laravel Package

Product Decisions This Supports

• Observability strategy: OTel-native vs. vendor SDK. The bundle emits spans/metrics through the OpenTelemetry API only — no Datadog/New Relic/Sentry SDK in application code. That keeps the backend choice a procurement decision rather than an architecture decision, and lets you switch vendors (or run OSS: Tempo/Jaeger/Prometheus) without touching product code. This is the single biggest strategic lever the package gives you.
• Build vs. buy for instrumentation. Out of the box it covers the four subsystems that generate most of your operational blind spots: HTTP kernel requests, console commands, Messenger (producer + consumer), and Doctrine. Building and maintaining equivalent span/metric wrappers in-house is typically 1–2 engineer-weeks up front plus ongoing semconv churn; adopting this shifts that to a dependency review. Reasonable "buy" (well, "adopt OSS") call for a mid-size Symfony estate.
• Roadmap sequencing for observability work. Every instrumentation is opt-in behind its own tracing.<feature>.enabled / metrics.<feature>.enabled node, with a per-feature blacklist regex. That means you can ship tracing subsystem-by-subsystem per service and turn off anything noisy without a redeploy of code — a phased rollout plan is a config decision, not an engineering project.
• Cost/latency visibility for AI features. The tracing side includes ai.platform / ai.agent / toolbox instrumentation with GenAI semconv attributes, and the metric guidance explicitly points at gen_ai.client.token.usage. If AI-assisted features are on the roadmap, this gives you token-spend and per-agent latency telemetry on the same rails as the rest of the app — directly supports pricing, quota, and model-routing decisions.
• Data-governance and PII decisions. The AttributeProviderInterface and the blacklist Voter are designed as swappable seams. "Don't emit customer identifiers / don't trace this endpoint class" becomes a supported configuration surface rather than a fork — which is what you need to answer a security review in days, not quarters.
• Cardinality and telemetry-spend control. Tracing and metrics are deliberately independent subscribers with independent toggles and separate naming conventions (_total, _seconds, _bytes). You can keep metrics (cheap, aggregate) while dropping high-volume spans (expensive) per subsystem — a real lever on observability bill.
• Platform/language constraint check. ⚠️ Despite the framing, this is a Symfony bundle, not Laravel. It does not serve Laravel services at all. If the estate is mixed, this informs a portfolio decision: standardize OTel as the contract across frameworks and pick per-framework instrumentation packages, rather than trying to standardize on one package.
• Vendor/maintenance risk posture. 28 stars, 0 dependents, effectively single-vendor (Worldia) stewardship. Active recent releases are a positive signal, but the decision this supports is "adopt with an owner and a fork plan," not "adopt and forget."

When to Consider This Package

Consider it when:

• The service is Symfony 6/7 with autowiring/autoconfiguration available, and you already have (or are committed to standing up) an OTLP endpoint — a collector, or a backend that speaks OTLP natively.
• You want semconv-compliant, framework-level spans for requests, commands, Messenger, and Doctrine without writing decorators yourself, and you value the bundle's enforced conventions (swappable attribute providers, operation-name resolvers, voter-based filtering) because it means your team won't diverge into bespoke span-naming per service.
• You are standardizing telemetry across multiple services and want a uniform shape for span names and attributes so dashboards and alerts are reusable.
• You need per-subsystem kill switches for rollout or for taming noisy instrumentations in production.
• You have, or can assign, an engineer to own the dependency — track upstream, pin versions, be ready to vendor a patch or fork. At this adoption level that's a half-day-per-quarter commitment, not zero.

Look elsewhere when:

• The target is Laravel. This bundle is a non-starter there. Use the OTel PHP contrib Laravel instrumentation or a managed agent instead; do not let the "PHP package" label create a false match in a build-vs-buy comparison.
• You've already bought a managed APM (Datadog, New Relic, Sentry, Elastic) and are happy with its agent. Its auto-instrumentation for Symfony is deeper and supported; adding this bundle mostly duplicates spans and doubles ingest cost.
• You need zero-code/zero-config coverage across many runtimes — the OTel PHP extension + auto-instrumentation, or a sidecar/agent model, is the better fit than a per-service Composer dependency you must add and keep current in every repo.
• You need vendor SLAs, security backports, or an escalation path. A 28-star, single-maintainer package cannot supply that; treat it as "good code you may have to own."
• You need coverage beyond these four subsystems — e.g. non-Messenger queue transports, custom cache layers, or deep HTTP-client edge cases. Extension is possible (the repo documents the five-part pattern), but budget engineering time; it's not config-only.
• You can't run an OTel collector or OTLP-capable backend. Without somewhere to send data, the bundle is inert overhead.

How to Pitch It (Stakeholders)

For executives (30 seconds). This is a free, open-source add-on that makes our Symfony services report their behavior — request timings, background job health, database calls, and AI token usage — in a vendor-neutral format called OpenTelemetry. The strategic value is optionality: we instrument once and can change monitoring vendors later without rewriting application code, and we can turn any noisy data source off per service via configuration. The risk is support: it's a small, single-vendor project with a thin user base, so adoption means we own the dependency and must be ready to fork it. Recommendation: pilot on one or two non-critical services for a sprint, with explicit exit criteria (data arrives, dashboards built, no measurable latency regression, upgrade path verified), before any wider mandate. Do not adopt it for Laravel services — it doesn't apply there.

For engineering leads. The bundle is well-architected for our purposes: it forces swappable attribute providers and operation-name resolvers rather than hardcoded span names, keeps tracing and metrics as independent subscribers so cost and cardinality can be tuned separately, and puts filtering behind regex voters we can override per feature. Integration is a Composer dependency plus a config block; there is no static-facade coupling in bundle code, so nothing reaches into our service container in an unfriendly way. The costs are real but bounded: we pin the version, we add it to the dependency-review list, and we assume we may need to carry a patch. The main thing I want from you in the pilot is a read on whether the Symfony request/Messenger/Doctrine coverage is sufficient — i.e. how much custom instrumentation we'd still have to write.

The ask. One sprint, one service, one engineer at partial allocation, plus a collector if we don't have one. Deliverable: trace and metric data flowing for requests + Messenger, a working dashboard, and a written go/no-go that names the owner and the fork contingency. If it's a go, rollout is config-only per service and can be sequenced to match product priorities — starting with the subsystems that map to current pain (background job reliability, then latency, then AI token spend).