Pawel Filipczak

Why Elastic donated its OpenTelemetry PHP distribution

Learn what the OpenTelemetry PHP distro donation changes for package-managed PHP environments, how it compares to existing options, and what contributors can do next.

7 min read
OpenTelemetry

We donated EDOT PHP to make OpenTelemetry for PHP as easy to deploy as any other runtime. PHP powers a significant number of websites and SaaS platforms, and we hope our contribution helps more teams adopt OpenTelemetry. In many production environments, runtimes are locked down and building native extensions during deploy is not possible, so we focused on an OS-package-first path (deb, rpm, apk) for zero-code instrumentation.

Since we announcement of the donation, we have been actively working on the project and are about to release a first beta version.

In this post, we will walk through what was donated, why it matters for production PHP systems, how it relates to existing OpenTelemetry PHP projects, and what is the status of the project.

Why PHP observability can still be hard

OpenTelemetry gives us a common standard, but deployment reality still matters. In many PHP environments, the blocker is not instrumentation APIs. The blocker is operations.

At Elastic, we are committed to open standards and to OpenTelemetry as the industry standard for observability data collection. To help the community with these operational constraints, we donated our EDOT PHP distribution to OpenTelemetry.

Common constraints include:

  • Shared hosting or hardened servers without build toolchains
  • Production images that cannot be rebuilt frequently
  • Package-managed PHP runtimes where OS-native install flows are required
  • Teams that need adoption without app code changes

This is where an OS-package distribution helps. If you can install a package and restart PHP, you can usually start collecting telemetry.

What the OpenTelemetry PHP distro provides

The project we donated combines native and PHP runtime components into one production path. The key features we announced in our original donation proposal are implemented and we are close to a first beta release. This includes:

  • Native extension and loader artifacts so teams can install prebuilt components instead of compiling in restricted environments.
  • Runtime/bootstrap logic for auto-instrumentation so applications can emit telemetry with little or no code changes.
  • Packaging support for deb, rpm, and apk so rollout fits existing Linux package management and operations workflows.
  • Background telemetry sending and automatic root span behavior so trace data is captured consistently without custom bootstrapping logic or blocking of the main flow.
  • OTLP protobuf serialization works out of the box, with no need for the ext-protobuf extension. This means teams don't have to install extra dependencies, which is especially important in PHP environments where adding new extensions is difficult or restricted.
  • Inferred spans so users get added visibility into work that is not explicitly instrumented in application code.
  • URL grouping for transaction/root spans so high-cardinality route data is easier to aggregate and analyze.
  • Built-in OpAMP support utilizing an OpAMP client already present in the agent.

For teams running PHP 8.1 through 8.4, this gives a practical onboarding path that fits existing OS package operations.

How installation looks in practice

A typical flow is simple:

  1. Install distro package for your Linux platform.
  2. Set exporter endpoint and auth headers.
  3. Restart PHP processes.
  4. Verify traces in your collector or backend.

Example environment variables:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://your-collector.example:4318"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <token>"

The key idea is predictable rollout through standard operational controls rather than custom build steps in each application pipeline.

For a detailed guide on how to setup the distro, see the setup documentation.

Relationship to existing OpenTelemetry PHP instrumentation

The current message from maintainers is coexistence with clear differentiation:

  • Distro path: package-managed, production-first, zero-code onboarding
  • Composer-centric path: more manual control and portability where that is needed

This distinction matters for users choosing a starting point. If you control application packaging tightly and can build extensions as part of app install, Composer-oriented paths can still be a fit. If you need an operations-first rollout through OS packages, the distro can reduce adoption friction.

The donation discussion also raised an important usability concern: too many overlapping options can confuse users. That is why compatibility and long-term alignment across projects is a key follow-up topic. The original proposal details are available in the OpenTelemetry community donation issue.

What to validate before broad production rollout

If you want to test this path in your own environment, validate these points early:

  • Runtime coverage: verify your PHP version and SAPI mode (PHP-FPM, Apache mod_php, CLI)
  • Packaging fit: confirm your distro package format and architecture support
  • Telemetry behavior: check span completeness, service naming, and exporter reliability
  • Operational safety: verify restart procedures, rollback steps, and version pinning policy

A lightweight validation matrix can save rework later, especially when multiple runtime profiles exist in the same organization.

The current status and what's next

With the completion of the initially-announced, above-mentioned features, we reached a significant milestone and are about to release a first beta version.

However, the work does not stop here. More enhancements and features are planned, including:

Class Shadowing

In some situations it is possible that the PHP distro loads classes that are already loaded by the application itself. This can lead to collisions and unexpected behavior. We are working on implementing shadowing of classes and namespaces of the PHP distro dependencies to avoid collisions. This new feature will increase the stability and reliability of the PHP distro across a wider range of applications.

Declarative Configuration Support

Just recently the OpenTelemetry community announced the stability of the declarative configuration specification. Including native support for the declarative configuration specification in the PHP distro is a feature that is on our roadmap and one of the next major features we will be working on. With declarative configuration support, teams will be able to configure the PHP distro in a more flexible way without having to modify their application code.

We are working on implementing declarative configuration support in the distro to allow for more fine-grained configuration of the agent. This new feature will increase the flexibility and usability of the PHP distro.

PHP 8.5 Support

In November 2025, PHP 8.5 was released with major changes to the language and runtime. We are working on supporting it in the PHP distro which will expand the scope of compatibility and usability of the PHP distro across a wider range of applications and environments.

Central Configuration Support

Both, the declarative configuration as well as the new proposal around telemetry policies are potential and promising enablers for dynamic, central configuration of OTel SDKs and distors. Once the discussion around telemetry policies is resolved, we will be able to implement central configuration support in the PHP distro. This will combine the concepts around declarative configuration, telemetry policies and the OpenTelemetry Agent Management Protocol (OpAMP) to provide a more flexible and powerful way to configure the PHP distro centrally.

Base EDOT on the upstream distribution

With the new OpenTelemetry PHP distro reaching a first beta release, we are working on basing Elastic's OTel PHP distribution (EDOT PHP) on the upstream distribution to increase the compatibility and avoid feature drift. This will ensure that the PHP distro is always up to date with the latest features and bug fixes from the OpenTelemetry community.

Conclusion

Our OpenTelemetry PHP distro donation is mainly about operational accessibility. It gives PHP teams a package-native way to adopt OpenTelemetry where build-time instrumentation is difficult. As community alignment progresses, we expect this to become a clearer and lower-friction option for production PHP observability. Try out the OpenTelemetry PHP distro repository, document gaps, and feed findings back to the maintainers.

Share this article

XFacebookLinkedInReddit