Webman集成Elastic APM进行应用性能管理-php教程-PHP中文网

elastic apm 官方 php agent 不支持 webman（基于 swoole），必须改用 opentelemetry php sdk + edot collector 方案；需在 webman 启动时单次初始化异步 otlphttpexporter，配置 apm-server 启用 otlp 接收，并在 onrequest/afterresponse 事件中精准管理 span 生命周期。

webman集成elastic apm进行应用性能管理

Elastic APM 能直接集成进 Webman，但必须绕过官方 PHP Agent 的限制——它不支持 Swoole 环境，而 Webman 基于 Swoole 运行。 你不能用 elastic/apm-agent-php composer 包，否则会报错或静默失效。正确路径是走 OpenTelemetry + EDOT（Elastic Distributions of OpenTelemetry）方案。

Webman 启动时无法加载 elastic/apm-agent-php

这是最常卡住的第一步。官方 PHP Agent 依赖 pcntl 和 curl 扩展，且内部使用阻塞式 HTTP 客户端，在 Swoole 的协程/多进程模型下会冲突。启动时可能无报错，但 Kibana 中完全看不到服务注册或追踪数据。

现象：apm-server 日志里没有收到任何数据，phpinfo() 查不到 elastic_apm 模块
根本原因：Swoole 的事件循环与 PHP Agent 的同步网络调用不兼容
替代方案：改用 opentelemetry-php SDK + otlp_exporter，配合 Elastic 自家的 EDOT Collector

用 OpenTelemetry SDK 替代 PHP Agent 的关键配置

Webman 是常驻内存的框架，必须确保 tracer 初始化只执行一次，且 exporter 使用异步、非阻塞方式上报。

Webman 2.2.0

Webman 2.2.0版本强化了 TCP/UDP 服务支持，优化路由组管理，并增强异步任务处理能力。结合协程与连接池技术，Webman 能轻松应对高并发场景，适用于网站、接口服务、即时通讯、物联网及游戏开发，兼具高性能、灵活扩展与稳定可靠，是多场景 PHP 服务开发的理想选择。

下载

在 start.php 或 bootstrap/app.php 中初始化 tracer，避免每次请求重复创建
exporter 必须设为 OtlpHttpExporter（不是 OtlpGrpcExporter），因为 Swoole 默认不启用 grpc 扩展
endpoint 地址格式为：http://<your-apm-server>:8200/v1/traces</your-apm-server>，注意路径末尾的 /v1/traces
务必设置 resource 标签，例如 service.name 和 service.version，否则 Kibana 无法识别服务名

use OpenTelemetry\SDK\Trace\TracerProvider;
use OpenTelemetry\Exporter\Otlp\Http\OtlpHttpExporter;
use OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor;

$exporter = new OtlpHttpExporter('http://localhost:8200/v1/traces');
$spanProcessor = new SimpleSpanProcessor($exporter);
$tracerProvider = new TracerProvider($spanProcessor);

// 注册为全局 tracer，Webman 请求生命周期内复用
\OpenTelemetry\API\Globals::setTracerProvider($tracerProvider);

APM Server 接收 OTLP 数据需显式启用

默认的 apm-server 配置只监听 APM 协议（/intake/v2/events），不处理 OTLP。若跳过这步，Webman 发出的 trace 会被 404 或 405 拒绝。

编辑 apm-server.yml，添加 otlp: 配置块
必须指定 host 和 port，且 port 不能和 host 冲突（例如不要同时用 8200）
启用 TLS 需额外配置证书；开发环境可先设 tls.enabled: false
重启 apm-server 后，检查日志是否出现 OTLP receiver started

otlp:
  host: "0.0.0.0:4318"
  tls:
    enabled: false

Webman 中间件注入 span 的边界容易错位

Webman 的中间件执行顺序和 Swoole 生命周期耦合紧密，若在错误时机 start span，会导致 span 跨越多个请求，或被提前 finish。

不要在 handle() 开头就 $tracer->spanBuilder()->startSpan() —— 此时 request 对象可能未 fully ready
推荐在 onRequest 事件回调中启动 root span，并通过 Context 透传
finish span 必须放在 response 发送之后（如 afterResponse 事件），否则 span duration 会偏短
手动 set attribute 时，避免写入敏感字段如 user.token，APM Server 默认会过滤含 password、token 的 key