作者：来自 Elastic Pawel Filipczak
了解 OpenTelemetry PHP distro 捐赠 对 package-managed PHP 环境 的变化， 它 与现有选项 的对比， 以及贡献者 接下来 可以做什么。
我们捐赠了 EDOT PHP，以使 OpenTelemetry for PHP 的部署像其他 runtime 一样简单。PHP 支撑着大量网站和 SaaS 平台，我们希望我们的贡献能帮助更多团队采用 OpenTelemetry。在许多生产环境中，runtime 被锁定，部署期间无法构建 native 扩展，因此我们专注于 OS-package-first 路径（deb、rpm、apk），实现零代码的检测。
自我们宣布捐赠以来，我们一直在积极推进该项目，并即将发布首个 beta 版本。
在本文中，我们将介绍捐赠内容、它对生产 PHP 系统的重要性、它与现有 OpenTelemetry PHP 项目的关系，以及项目的当前状态。
为什么 PHP 可观测性仍然困难
OpenTelemetry 提供了一个通用标准，但部署现实依然重要。在许多 PHP 环境中，阻碍因素并非 instrumentation API，而是运维。
在 Elastic，我们致力于开放标准，并将 OpenTelemetry 作为可观测性数据收集的行业标准。为帮助社区应对这些运维约束，我们将 EDOT PHP 发行版捐赠给了 OpenTelemetry。
常见约束包括：
-
共享主机或经过加固的服务器，没有构建工具链
-
生产镜像不能频繁重建
-
需要 OS-native 安装流程的 package-managed PHP runtime
-
团队希望无需修改应用代码即可采用
这时 OS-package 发行版就能派上用场。如果你可以安装一个包并重启 PHP，通常就能开始收集 telemetry。
OpenTelemetry PHP distro 提供的功能
我们捐赠的项目将 native 和 PHP runtime 组件结合成一个生产路径。我们在最初的捐赠提案中宣布的关键功能已经实现，并且接近首个 beta 版本发布。这包括：
-
Native 扩展和 loader 工件，让团队可以安装预构建组件，而不是在受限环境中编译
-
Runtime/bootstrap 逻辑实现自动 instrumentation，使应用程序几乎无需修改代码即可发出 telemetry
-
支持 deb、rpm 和 apk 打包，使部署符合现有 Linux 包管理和运维流程
-
后台 telemetry 发送和自动 root span 行为，确保 trace 数据被一致捕获，无需自定义 bootstrap 逻辑或阻塞主流程
-
OTLP protobuf 序列化开箱即用，无需 ext-protobuf 扩展，这意味着团队不必安装额外依赖，这在 PHP 环境中尤其重要，因为新增扩展可能困难或受限
-
推断 spans，使用户能够获得对应用代码中未显式 instrumentation 的工作的可见性
-
事务/根 span 的 URL 分组，使高基数路由数据更容易聚合和分析
-
内置 OpAMP 支持，利用 agent 中已有的 OpAMP 客户端
-
对运行 PHP 8.1 到 8.4 的团队，这提供了一条符合现有 OS 包操作的实际入门路径
实际安装示例
典型流程很简单：
-
为你的 Linux 平台安装 distro package。
-
设置 exporter endpoint 和 auth headers。
-
重启 PHP 进程。
-
在你的 collector 或 backend 中验证 traces。
示例环境变量：
`
1. export OTEL_EXPORTER_OTLP_ENDPOINT="https://your-collector.example:4318"
2. export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <token>"
`AI写代码
核心思想是通过标准的运维控制实现可预测的部署，而不是在每个应用流水线中执行自定义构建步骤。
有关如何设置 distro 的详细指南，请参阅设置文档。
与现有 OpenTelemetry PHP instrumentation 的关系
维护者目前的建议是共存但需明确区分：
-
Distro path：以 package-managed、production-first、zero-code onboarding 为主
-
Composer-centric path：在需要更多手动控制和可移植性时使用
这一区分对用户选择起点很重要。如果你能严格控制应用打包，并且可以在应用安装时构建扩展，Composer-oriented paths 仍然适用。如果你需要通过 OS packages 进行运维优先的部署，distro 可以减少采用摩擦。
捐赠讨论还提出了一个重要的可用性问题：过多重叠的选项可能会让用户困惑。因此，跨项目的兼容性和长期一致性是后续重点。原始提案详情可在 OpenTelemetry 社区捐赠问题中查阅。
在大规模生产部署前需要验证的事项：
-
Runtime coverage：验证你的 PHP 版本和 SAPI 模式（PHP-FPM、Apache mod_php、CLI）
-
Packaging fit：确认 distro package 格式和架构支持
-
Telemetry behavior：检查 span 完整性、服务命名和 exporter 可靠性
-
Operational safety：验证重启流程、回滚步骤和版本固定策略
一个轻量级的验证矩阵可以避免后期返工，尤其在组织内存在多个 runtime 配置时。
当前状态与下一步计划
随着最初宣布的功能完成，我们已达到一个重要里程碑，即将发布第一个 beta 版本。
然而，工作不会停止。更多增强功能计划中，包括：
-
Class Shadowing
在某些情况下，PHP distro 可能加载应用已加载的类，这可能导致冲突和意外行为。我们正在实现 PHP distro 依赖类和命名空间的 shadowing，以避免冲突。该新功能将提高 PHP distro 在更广泛应用中的稳定性和可靠性。 -
Declarative Configuration Support
最近 OpenTelemetry 社区宣布 declarative configuration 规范稳定。PHP distro 原生支持 declarative configuration 是我们路线图上的功能之一。通过 declarative configuration，团队可以在不修改应用代码的情况下更灵活地配置 PHP distro。我们正在实现该功能，以允许更精细的 agent 配置，从而提升灵活性和可用性。 -
PHP 8.5 Support
2025 年 11 月，PHP 8.5 发布，带来语言和 runtime 的重大变化。我们正在支持 PHP 8.5，这将扩大 PHP distro 的兼容性和可用性范围。 -
Central Configuration Support
declarative configuration 以及 telemetry policies 新提案为 OTel SDK 和 distros 的动态中央配置提供可能。一旦 telemetry policies 讨论完成，我们将能在 PHP distro 中实现 central configuration 支持。这将结合 declarative configuration、telemetry policies 和 OpenTelemetry Agent Management Protocol (OpAMP) 概念，提供更灵活强大的中央配置方式。 -
基于上游 distribution 构建 EDOT
随着 OpenTelemetry PHP distro 发布第一个 beta 版本，我们将基于上游 distribution 构建 Elastic 的 OTel PHP distribution（EDOT PHP），以提高兼容性并避免功能偏离。这将确保 PHP distro 与 OpenTelemetry 社区的最新功能和 bug 修复保持同步。
结论
我们捐赠的 OpenTelemetry PHP distro 主要关注运维可访问性。它为 PHP 团队提供了一种 package-native 的方式来采用 OpenTelemetry，即使在 build-time instrumentation 困难的环境中也可使用。随着社区对齐的推进，我们预计这将成为生产环境 PHP observability 的更清晰、摩擦更小的选项。试用 OpenTelemetry PHP distro 仓库，记录差距，并将发现反馈给维护者。
