PHP 零代码接入¶

Beacon PHP 要求 PHP 8.2 或更高版本、安装在应用中的 Composer 包，以及匹配运行环境的 Beacon 原生扩展。

接入前，请先完成公共配置，开启 DataKit OpenTelemetry 采集器。以下命令以 Linux/macOS Shell 为例，假设应用与 DataKit 部署在同一主机；跨主机或容器部署时，请替换 127.0.0.1 并调整监听地址。

安装¶

1. 在原生扩展发布页面下载与 PHP 版本、线程安全模式、操作系统和架构匹配的构建，并启用该扩展。
2. 在应用根目录创建 .beacon 目录，从 Beacon PHP 发布页面下载 Composer ZIP 制品并放入该目录，再安装应用实际使用的框架探针：

composer config repositories.beacon artifact "$PWD/.beacon"
composer require beacon-observability/beacon-php
vendor/bin/beacon-php install pdo guzzle

运行 vendor/bin/beacon-php components 可查看其他组件别名。

启动¶

export OTEL_PHP_AUTOLOAD_ENABLED=true
export OTEL_SERVICE_NAME=my-php-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:9529/otel
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
vendor/bin/beacon-php doctor
php public/index.php

使用 PHP-FPM 时，请在服务环境中配置相同变量并重启 Worker。Beacon PHP 当前不提供 Profile 组件。

调试与诊断¶

先生成运行环境诊断报告，再开启 SDK 内部诊断日志。沿用上文的自动加载和 OTLP 配置：

vendor/bin/beacon-php doctor --json > beacon-php-doctor.json
OTEL_LOG_LEVEL=debug OTEL_PHP_LOG_DESTINATION=stderr \
  php public/index.php > beacon-php-debug.log 2>&1

doctor 检查 PHP、原生扩展、SDK、Exporter、组件和零代码配置；它不验证一次实际的 OTLP 投递。OTEL_PHP_LOG_DESTINATION=stderr 将 SDK 内部日志写入标准错误，上述命令将其保存到文件。

PHP-FPM 需要在实际 Worker 的环境中注入这两个变量，重启 Worker，并按 FPM 的日志配置收集标准错误。CLI 与 FPM 可能使用不同的 php.ini、扩展和环境变量，CLI 的 doctor 结果不能代替 FPM 运行环境检查。

排障后恢复原启动命令，或从 FPM/服务配置中移除调试变量并重启。

验证接入¶

访问应用接口，产生经过受支持框架或依赖库的请求，再进入观测云「应用性能监测 > 链路」，按上文服务名筛选。完整检查步骤参见公共配置，无数据时参见故障排查。