PHP链路追踪需扩展+report_client组合实现，仅配extension=skywalking.so无法上报；必须显式开启skywalking.enable=1，设置合法app_code、正确grpc地址及可写log_path，并确保report_client进程正常运行且能连通OAP。
PHP 本身不支持 SkyWalking 原生 JavaAgent 方式，必须通过独立的 PHP 扩展 + 外部上报进程（report_client）组合实现链路追踪；直接在 php.ini 里加个 extension=skywalking.so 并不能自动上报数据，漏掉 report_client 运行环节会导致所有 trace 丢失。
编译安装 skywalking-php-sdk 扩展失败：常见报错和修复点
最常卡在 make 阶段报 undefined reference 到 grpc 或 protobuf 符号。这是因为扩展依赖 gRPC C++ 库，但系统未预装或版本不匹配。
- 确认已安装
libgrpc-dev、libprotobuf-dev（Ubuntu/Debian）或grpc-devel、protobuf-devel（CentOS/RHEL） - 编译前执行
export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig"（若手动编译过 gRPC） - 运行
phpize --version确保与当前 PHP 版本一致（如 PHP 8.2 就不能用 PHP 7.4 的 phpize） - 若仍失败，改用官方预编译包（见 GitHub
skywalking-php-sdk/releases），解压后将skywalking.so拷入extension_dir路径
agent.config 不起作用：PHP 探针不读取 Java Agent 配置文件
PHP 探针完全不兼容 Java Agent 的 agent.config。它的配置项全靠 php.ini 控制，且部分参数名和语义与 Java 版不同。
-
skywalking.enable=1必须显式开启，否则扩展静默不工作 -
skywalking.grpc=127.0.0.1:11800是 OAP 的 gRPC 地址，不是 UI 地址（UI 默认是8080） -
skywalking.app_code必须设置，且不能含空格或下划线（建议用短横线，如user-service），否则 UI 中服务名显示为空或乱码 -
skywalking.log_path路径需 PHP 进程有写权限，且目录必须存在（mkdir -p /tmp/skywalking）
report_client 启动后无数据：端口、日志路径、权限三连查
report_client 是真正把 PHP 扩展写入的日志文件转换为 gRPC 请求发给 OAP 的“搬运工”，它挂了，整个链路就断在本地磁盘上。
立即学习“PHP免费学习笔记（深入）”；
- 启动命令必须带两个参数：
report_client <port><log_path></log_path></port>，例如report_client 127.0.0.1:11800 /tmp/skywalking - 确保
report_client可执行（chmod +x /usr/bin/report_client） - 检查
report_client进程是否存活：ps aux | grep report_client - 查看其 stderr 输出（建议重定向到文件）：
report_client 127.0.0.1:11800 /tmp/skywalking 2>&1 > /var/log/skywalking-report.log - OAP 的 gRPC 端口（默认
11800）必须可被report_client访问（容器环境注意 network mode 或 host 网络）
WebUI 中看不到 PHP 服务：命名、采样、存储三处易忽略
即使 report_client 正常运行，PHP 服务也可能在 UI 的「Service」列表中完全不可见——问题往往不在传输链路，而在数据落库或识别逻辑。
- 确认 OAP 配置的 storage 类型（如
elasticsearch）与实际部署一致，且索引模板已加载（ES 7.x+ 需手动执行curl -X PUT ...导入模板） - PHP 探针默认采样率是 100%（
skywalking.sample_n_per_3_secs=-1），但若误设为0，则一条 trace 都不会生成 - 检查 OAP 日志中是否有
Invalid service name或gRPC client disconnected报错 - PHP 服务名（
skywalking.app_code）需与其它语言服务统一命名规范，否则跨语言调用链无法拼接（如 Java 服务叫order-service，PHP 就不能叫order_api）
真正容易被跳过的点是：PHP 扩展只负责写日志，report_client 负责读日志并上报，OAP 负责解析入库，三者任意一环出问题，UI 就是空白。排查时不要只盯着 PHP，得顺着手动检查每个环节的输出和状态。
