[Donation Proposal]: Elastic distribution of OpenTelemetry for PHP (elastic/elastic-otel-php)

[intuibase]

Project description

This project provides an OpenTelemetry PHP Distribution designed for production use, with fully automated packaging and installation.

Unlike the vanilla opentelemetry-php SDK or the opentelemetry-php-instrumentation, which require manual setup and build steps, this distro is delivered as native OS packages (RPM, DEB, APK). These packages enable OpenTelemetry instrumentation out-of-the-box, without requiring changes to the application or its deployment process.

Additionally, the project includes a new PHP extension implemented in C++20, designed to:

• Reduce long-term maintenance burden
• Provide better performance, memory management, and runtime stability
• Enable advanced features not easily achievable in pure PHP implementations

Key Differences from Existing OpenTelemetry PHP Projects

While opentelemetry-php-instrumentation also provides automatic instrumentation capabilities, it still requires manual installation of the PHP extension (compilation, dependency management, and packaging), app-level configuration, and changes to deployment pipelines. In many environments (e.g., shared hosting, locked-down production environments), these steps are impractical.

The Elastic Distribution (EDOT PHP) eliminates this friction:

• Automated setup:

  • Delivered as native OS packages
  • Extension is compiled, version-matched, and ready to use for all installed PHP versions
  • Instrumentation works automatically after installation and a simple app restart

• No application changes required:

  • No modification of the app package
  • No redeployment needed
  • No manual SDK/instrumentation configuration

• Additional production-grade features:

  • Background sending of telemetry (non-blocking)
  • Inferred spans to enrich traces without custom instrumentation
  • Automatic transaction spans and grouping
  • Built-in native Google Protobuf serialization (no need for ext-protobuf)
  • Upcoming support for:
    • Dynamic configuration via OpAMP
    • Dedicated process for telemetry sending and config distribution
    • gRPC-based background sending
    • Worker metrics aggregation or shared storage

• Broader compatibility:

  • Supports PHP 8.1 and newer (vs vanilla SDK which supports native instrumentation starting from PHP 8.2)

Zero-Config Onboarding

After installing the package via your OS package manager, OpenTelemetry instrumentation is enabled immediately — without requiring environment variable setup, SDK code changes, or configuration steps. This drastically reduces the barrier to adoption, especially in enterprise or legacy environments.

Benefits to the OpenTelemetry community

The PHP ecosystem has unique characteristics:

• Applications often run in environments where changes to the app code or deployment are difficult or not allowed (modifying application code is impractical, rebuilding containers is not feasible)
• Containers or shared hosts typically rely on OS package-based PHP distributions
• Many environments lack compilers or development tools needed to build native extensions

This distro is designed specifically for such scenarios. It expands OpenTelemetry adoption by:

• Providing a frictionless alternative for environments where the vanilla SDK is difficult to use
• Requiring no developer effort to enable instrumentation
• Making OpenTelemetry accessible to legacy, restricted, or production-locked PHP systems

Importantly, this project complements existing OpenTelemetry PHP efforts — it does not replace or compete with them. It offers a different deployment model and introduces a native runtime optimized for performance and stability.

Reasons for donation

Elastic is dedicated to OpenTelemtry’s vision to make it the single, ubiquitous standard and framework for Observability. With this donation, we strive to help OpenTelemetry to successfully instrument PHP applications without requiring changes to the application or their deployment by donating our OpenTelemetry PHP Distro to OpenTelemetry’s ecosystem.

Repository

https://github.com/elastic/elastic-otel-php

Existing usage

The elastic-otel-php project is already used in production environments by Elastic users as the default OpenTelemetry-based PHP agent distribution.

It is:

• Packaged and shipped as part of the Elastic offering
• Deployed in customer production environments across various Linux distributions using RPM, DEB, and APK packages
• Integrated with Elastic Observability, but designed to be vendor-neutral and compatible with any OpenTelemetry backend
• Tested in real-world PHP applications (including high-throughput workloads and legacy environments)
• Used in containerized and non-containerized deployments, including common PHP stacks (e.g., Apache + mod_php, PHP-FPM, CLI scripts)

The distro has been in active development and production use since April 2025 and has helped users instrument their applications with minimal effort — particularly in environments where modifying application code or redeploying containers is not feasible.

Maintenance

Pawel Filipczak (@intuibase) and Sergey Kleyman (@SergeyKleyman) would like to remain one of the maintainers of the project after donation.
We are committed to working in the open and collaborating with the OpenTelemetry community under CNCF governance.

Licenses

The project is already open source using Apache 2.0 license (same as OpenTelemetry). This makes the code easy to access for review and evaluation of the donation proposal in the next few weeks.

Trademarks

Currently, the codebase uses the word Elastic in namespace names and in some configuration options and we do not intend to donate any code that includes the name “Elastic”. We will make sure that any use of the "Elastic" as name is removed or neutralized in the codebase should the donation be accepted, in alignment with OpenTelemetry community guidelines and CNCF neutrality principles.

Other notes

Proposed target repository name

opentelemetry-php-distro
(as suggested in open-telemetry/community#2644)

Post-donation tasks

Upon acceptance of this donation, we plan to perform the following tasks to align the project with OpenTelemetry community expectations:

• Change Elastic namespaces in the code to OpenTelemetry (or other agreed neutral naming)
• Modify vendor-specific configuration options:
  • Rename ELASTIC_OTEL_* options to either OTEL_* or OTEL_PHP_* (to be agreed with SIG PHP and the community)
• Prepare and align CI/CD pipelines for the new repository
• Open an Elastic-hosted Conan repository or migrate the Conan packages to another community-accessible repository
• Update relevant OpenTelemetry PHP documentation to include this distro as an official option

We look forward to collaborating with the community on these efforts.

[intuibase]

@open-telemetry/php-maintainers

[svrnm]

@intuibase @SergeyKleyman, thank you for offering the donation! I'll work with you on going through the Donation process! We (@open-telemetry/governance-committee) discussed this yesterday in our meeting and are in favor of making this happen, especially since @open-telemetry/php-maintainers are interested in having this donation done as well!

A few questions:

What's the difference and relationship between the donation and the existing opentelemetry-php-instrumentation? Is the donated code going to supersede the existing project, or is it an alternative? If it is superseding, what would be the timeline for that, and if it is an alternative, who would prefer which solution? Or, is there a dependency between the two, that the donated code builds on top of the instrumentation?

Are existing @open-telemetry/php-maintainers going to contribute to the donated code as well, or will this only be maintained by @intuibase and @SergeyKleyman?

[intuibase]

Thanks for the great question @svrnm - here’s a bit more detail on how the donated project relates to opentelemetry-php-instrumentation.

There is some overlap between the two - particularly in the native extension layer:

• Both opentelemetry-php-instrumentation and the native part of EDOT PHP (the donated project) expose similar mechanisms to instrument userland functions or PHP extensions.
• In both cases, this is achieved via a hook() function that allows registering instrumentation callbacks.

However, the EDOT PHP extension goes much further in terms of production readiness and features:

• It includes:
  • Fully automatic instrumentation (no changes needed in application code or runtime environment)
  • Background sending to reduce latency
  • Inferred spans and automatic root span creation
  • Native Protobuf serialization, eliminating the need for separate Google extensions
• It is delivered as precompiled system packages (rpm, deb, apk) with the extension already built and configured.
  • This simplifies deployment significantly — no build tools or PECL needed.

By contrast:

• opentelemetry-php-instrumentation is a lightweight, Composer-oriented project that builds the extension at install time.
  • This makes it easier to use on exotic platforms or architectures not currently supported by the distro.
  • It’s a great fit for developers who want full control over their instrumentation stack.

In summary

• The donated distro builds on the same core ideas, but is optimized for zero-config, production-grade, OS-integrated deployment.
• opentelemetry-php-instrumentation remains valuable as a flexible and portable option, especially where the distro is not available.
• We see the two solutions as complementary, and we’re open to collaborating on shared functionality and long-term alignment.

At this stage, we are not proposing to replace opentelemetry-php-instrumentation - both projects can coexist and serve different needs.
However, in the future, if we’re able to support a broader range of platforms and architectures, we’d be open to revisiting that discussion.

[svrnm]

At this stage, we are not proposing to replace opentelemetry-php-instrumentation - both projects can coexist and serve different needs.
However, in the future, if we’re able to support a broader range of platforms and architectures, we’d be open to revisiting that discussion.

While you are not proposing it, I'd like to look into this possibility nevertheless. From what I see right now the key difference is that it supports some additional platforms and architectures? I don't understand what "full control over their instrumentation stack" means in the context of an automatic instrumentation, since that's when developers should use the SDK?

Maybe the donation could be a "version 2" of the opentelemetry-php-instrumentation?

To add some context why I am pushing on this topic:

• we (OpenTelemetry project) already provide a bouquet of solutions on how people can use and get started, there is the SDK, the existing instrumentation, there is the eBPF based instrumentation (which might support php at some point as well), so if we add another option to it, it becomes confusing for end users and really hard to make a decision.
• there are already limited resources for SIG PHP, so if we split that across 3 projects instead of 2 all the things move slower, so I'd rather see focus on 2, even if one needs to be deprecated at some point

I am also curious to hear what @open-telemetry/php-maintainers think? Do you see a viable option to have only one automatic instrumentation for PHP, or do we need both?

Note, that I am OK with the proposal, and if the answer to my questions is "no, we can't do that", let's go with it!