Sdk Configuration Laravel Package

Product Decisions This Supports

• Build vs. buy on telemetry configuration. Decide whether to keep hand-rolling OTEL_* env-var plumbing (and our own validation, precedence rules, and defaults) or delegate to the OpenTelemetry spec-backed configuration format. This package is the "buy" side of that trade-off, at effectively zero cost.
• Feature/roadmap: config-as-file for observability. Supports a roadmap item like "ship an otel-config.yaml next to config/" so instrumentation settings, exporters, samplers, and resource attributes live in reviewable config rather than in deploy-time environment variables.
• Vendor neutrality as a product hedge. Keeping configuration in a spec-aligned format means swapping Datadog → New Relic → Grafana → an OTel Collector is a config diff, not a code change. That's a strategic decision about lock-in, not a technical one.
• Ops-owned cost control. Per-environment sampling rates and exporter endpoints become something SRE can tune without a release — a lever on telemetry spend, which is usually the largest surprise line item in observability budgets.
• Multi-tenant / per-service differentiation. Different sampling or resource attributes per tenant or per service become data, not code branches.
• Distribution and framework-integration strategy. If we maintain an internal Laravel package, base image, or scaffold, this determines whether we build on the official SDK's config layer or invent a competing schema.
• Dependency-surface decisions. Whether to depend on open-telemetry/sdk (meta) and treat this as transitive, or take a direct dependency on a READONLY subpackage split.

Caveat to weigh in the decision record: the 0 stars / 0 dependents signal is misleading — this is a READONLY subtree split of the opentelemetry-php monorepo, so adoption is measured on the parent, not here. The honest risk read is that the OTel configuration specification itself is still stabilizing; the API surface will move.

When to Consider This Package

Adopt when:

• We're already on open-telemetry/sdk for PHP and want file/YAML-driven configuration instead of a growing wall of environment variables.
• We maintain a distribution, framework integration, or internal platform package that must read and merge telemetry config on behalf of application teams.
• We need structured, programmatic configuration objects to hand to the SDK, not just a parser.
• We want spec-aligned config so multiple languages/services in our estate share one file format and one mental model.
• We want to isolate observability decisions from application code and give ops a supported surface.

Look elsewhere when:

• A handful of env vars genuinely suffices — the full declarative config surface is overkill and adds a failure mode.
• We are not using the OpenTelemetry PHP SDK. This package produces config for that SDK; it has no standalone value.
• We need stable, guaranteed APIs today. Treat the interface as experimental; the underlying spec is still evolving.
• We want a batteries-included Laravel experience. Use the official SDK plus instrumentation packages (or a vendor agent) — not this low-level building block.
• We need identical behavior across non-PHP services now. The format is cross-language but this implementation is PHP-only; parity is aspirational.
• The team has no appetite for wrapping dependencies. Taking this directly without a facade invites upgrade churn.

Practical guidance: consume open-telemetry/sdk and let this arrive transitively; pin versions; wrap it behind our own config resolver so the spec's evolution is absorbed in one place.

How to Pitch It (Stakeholders)

For executives (30 seconds): This is a small, free, Apache-2.0 plumbing dependency inside OpenTelemetry's official PHP SDK. It lets our telemetry be configured in a file rather than hardcoded. The business value is twofold: we can change observability vendors with a config edit instead of an engineering project — real leverage in renewal negotiations — and operations can turn down sampling to control telemetry cost without shipping a release. There is no new infrastructure, no license, and no vendor commitment. The only risk is that the configuration spec is still maturing, which we contain by hiding it behind our own thin config layer. Recommendation: pilot on one service, don't expose it to customers yet.

For engineering (the ask): Don't take a direct dependency. Add open-telemetry/sdk, treat sdk-configuration as transitive, and put a facade in front of it — our own TelemetryConfig value object that maps our existing env vars into the spec schema and can later read a YAML file. Budget roughly one sprint for a spike, most of it spent reconciling our current env-var conventions with the spec's precedence and merge rules. Success criteria: one service running entirely off config file, ops able to change the sampler without a deploy, and no application code importing the OTel config classes directly. Known unknowns: spec churn between minor versions and thin documentation — assume we'll be reading the spec, not the README.