Elastic APM 官方 PHP Agent 不支持 Webman（基于 Swoole），必须改用 OpenTelemetry PHP SDK + EDOT Collector 方案；需在 Webman 启动时单次初始化异步 OtlpHttpExporter，配置 apm-server 启用 OTLP 接收，并在 onRequest/afterResponse 事件中精准管理 span 生命周期。
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-phpSDK +otlp_exporter，配合 Elastic 自家的EDOTCollector
用 OpenTelemetry SDK 替代 PHP Agent 的关键配置
Webman 是常驻内存的框架，必须确保 tracer 初始化只执行一次，且 exporter 使用异步、非阻塞方式上报。
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
真正麻烦的不是代码怎么写，而是 Webman 的常驻进程模型让 span 生命周期和传统 PHP-FPM 完全不同——你得自己管理 context 传递、span 关闭时机、以及 exporter 的连接复用。漏掉任一环，Kibana 里就只剩空的服务列表。
