Webman集成OpenTelemetry需适配协程：Span上下文须手动attach绑定，OTLP exporter需改用GrpcExtension并调优超时，禁用auto-instrumentation，指标改用OTLPMetricExporter推送，TracerProvider须按worker进程单独实例化。
Webman 项目直接集成 OpenTelemetry 时，opentelemetry-php SDK 的默认行为不兼容其协程调度模型，会导致 span 上下文丢失、采样率失效、甚至内存泄漏——这不是配置问题，而是运行时环境冲突。
Webman 协程环境下 Span 上下文丢失
Webman 基于 Swoole 协程，而 opentelemetry-php 默认使用 PHP 原生的 Context 存储（基于全局变量或 ThreadLocal），在协程切换时无法自动传递 span。结果是：中间件、路由、数据库调用等环节生成的 span 全部脱离父链，变成孤立根 span。
- 典型现象：
jaeger-query中看到大量单 span 的“孤岛”，trace_id不连续，parent_span_id为空 - 必须显式使用
Context::storage()->attach()绑定上下文，且需在每个协程入口（如onRequest）手动恢复 -
OpenTelemetry\SDK\Trace\TracerProvider初始化后，需搭配Swoole\Coroutine\Channel或Co::getcid()做上下文隔离，否则跨协程污染
OTLP exporter 在 Webman 中超时失败
Webman 的 HTTP server 默认关闭长连接，而 OTLPSpanExporter 使用 gRPC over HTTP/2，依赖稳定的连接池和合理的超时控制。直接复用 Laravel 或 CLI 场景下的配置会频繁报 DeadlineExceeded 或 Unavailable 错误。
Webman 2.2.0版本强化了 TCP/UDP 服务支持，优化路由组管理，并增强异步任务处理能力。结合协程与连接池技术，Webman 能轻松应对高并发场景，适用于网站、接口服务、即时通讯、物联网及游戏开发，兼具高性能、灵活扩展与稳定可靠，是多场景 PHP 服务开发的理想选择。
- 关键参数必须重设：
timeout至少 10s（默认 3s 不够），connect_timeout≥ 5s，且禁用keep_alive（Swoole 不支持 HTTP/2 keep-alive） - 不能复用
curlhandler；必须改用GrpcExtension（需提前安装grpc扩展），否则 fallback 到 cURL 会阻塞协程 - 建议将 exporter 封装为单例并复用连接，避免每次 span 导出都新建 gRPC channel
自动插桩（auto-instrumentation）与 Webman 冲突
opentelemetry-auto-instrumentation 的 PHP agent 假设应用是传统 FPM 模式，它通过 auto_prepend_file 注入 hook，但在 Webman 的协程生命周期中会引发重复初始化、静态变量污染、以及 register_shutdown_function 失效等问题。
- 禁用所有 auto-instrumentation 配置项，包括
OTEL_PHP_AUTOLOAD_PATH和OTEL_PHP_EXTENSION_DIR - 数据库、Redis、HTTP client 等组件必须手动 wrap：例如用
OpenTelemetry\Instrumentation\PDO\PDOTracing替代原生PDO实例 - Webman 的
HttpDispatcher和MiddlewarePipeline是唯一可靠的手动埋点入口，其他位置（如事件监听器）可能因协程调度顺序错乱
指标（Metrics）上报卡在 Prometheus Receiver
Webman 自身不暴露 /metrics 端点，而 OpenTelemetry 的 PrometheusExporter 是 pull 模式，需被 Prometheus 主动抓取。若直接启用，会因无 HTTP server 对应路径导致数据不可见。
- 不要用
PrometheusExporter，改用OTLPMetricExporter推送至 Collector - Collector 端必须启用
prometheusremotewritereceiver，并配置remote_write指向 Prometheus 的/api/v1/write - Webman 的
Timer::tick()是唯一安全的指标采集触发点，避免在协程内频繁调用counter->add()引发竞争
最易被忽略的是：Webman 的 onWorkerStart 钩子中初始化 TracerProvider 时，必须对每个 worker 进程单独 new 一个 TracerProvider 实例，而不是全局单例——Swoole worker 进程间不共享内存，共用会导致 span 数据写入错乱或崩溃。
