Composer 安装 php-opentelemetry 失败是因为官方未发布 open-telemetry/opentelemetry 包，仅提供 open-telemetry/sdk:^1.0（PHP 8.1+），需手动配置 Jaeger/Zipkin exporter 并调用 $span->end()。
Composer 安装 php-opentelemetry 失败或找不到包？
直接运行 composer require open-telemetry/opentelemetry 会报错：Package open-telemetry/opentelemetry not found。这是因为官方 SDK 没有发布稳定版 Composer 包，当前（2024 年中）唯一可用的正式发布包是 open-telemetry/sdk，且仅支持 PHP 8.1+，依赖 ext-grpc 或 ext-curl（后者功能受限）。
常见错误现象：Could not find package open-telemetry/opentelemetry、require-dev open-telemetry/sdk: No version set、安装后 OpenTelemetry\SDK\Trace\TracerProvider 类无法自动加载。
- 确认 PHP 版本 ≥ 8.1（
php -v），低于该版本无法安装 - 运行
composer require open-telemetry/sdk:^1.0（不要省略^1.0，否则可能匹配到未发布的 dev 分支） - 若提示缺少
ext-grpc，可临时用composer require open-telemetry/sdk:^1.0 --ignore-platform-reqs，但后续必须手动配置 exporter（如 OTLP over HTTP） - 安装后检查
vendor/autoload.php是否已加载，且OpenTelemetry\SDK\Trace\TracerProvider::getDefault()能正常调用
PHP 中初始化 TracerProvider 并导出 trace 到 Jaeger/Zipkin
SDK 默认不启用任何 exporter，必须显式配置。直接 new TracerProvider 不生效，需通过 TracerProvider::builder() 链式构建并注册全局实例。
使用场景：Laravel、Symfony 或原生 PHP 应用启动时初始化；不建议在每次请求中重复创建。
立即学习“PHP免费学习笔记（深入）”；
use OpenTelemetry\SDK\Trace\TracerProvider;
use OpenTelemetry\SDK\Trace\Exporter\JaegerExporter;
use OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor;
$exporter = new JaegerExporter(
'http://localhost:14268/api/traces', // Jaeger Collector HTTP endpoint
null, // auth header（如需）
'my-service-name'
);
$processor = new SimpleSpanProcessor($exporter);
$tracerProvider = TracerProvider::builder()
->addSpanProcessor($processor)
->build();
// 必须设置为全局，否则 tracer 获取不到
TracerProvider::setDefault($tracerProvider);
- Jaeger HTTP endpoint 是
/api/traces，不是/api/v2/spans（后者是 Thrift over HTTP，PHP SDK 不支持） - Zipkin 需用
OpenTelemetry\SDK\Trace\Exporter\ZipkinExporter，endpoint 为http://localhost:9411/api/v2/spans -
SimpleSpanProcessor同步发送，高并发下影响性能；生产环境应换用BatchSpanProcessor并配置maxQueueSize和scheduledDelay
手动创建 span 时 context 丢失或 parent span 不继承
PHP 的 OpenTelemetry SDK 默认不自动注入 HTTP 请求上下文，startSpan() 创建的 span 总是 root span，除非显式传入 parent context。
容易踩的坑：在中间件或路由处理函数里直接 $tracer->startSpan('handle-request')，结果所有 span 都平级，无法形成调用链。
- 从传入的
$_SERVER提取traceparent字段：$traceParent = $_SERVER['HTTP_TRACEPARENT'] ?? null - 用
OpenTelemetry\Context\Context::getCurrent()获取当前 context，再用TraceContextPropagator::getInstance()->extract($carrier)注入远程 context（需先use OpenTelemetry\Propagation\TraceContextPropagator） - 创建 span 时必须指定 parent：
$span = $tracer->startSpan('db-query', [], $parentContext) - 忘记调用
$span->end()会导致 span 永久挂起，内存泄漏；建议用 try/finally 或 register_shutdown_function 保底结束
为什么 trace 数据没出现在 Jaeger UI？
最常见原因是 span 没 end、exporter 配置错误、或网络不通，而非 SDK 初始化失败。
验证步骤：先关闭所有中间件，写一个最小脚本直连 exporter，排除框架干扰。
// test-trace.php
require __DIR__.'/vendor/autoload.php';
use OpenTelemetry\SDK\Trace\TracerProvider;
use OpenTelemetry\SDK\Trace\Exporter\JaegerExporter;
use OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor;
$exporter = new JaegerExporter('http://localhost:14268/api/traces');
$processor = new SimpleSpanProcessor($exporter);
$tp = TracerProvider::builder()->addSpanProcessor($processor)->build();
TracerProvider::setDefault($tp);
$tracer = $tp->getTracer('test');
$span = $tracer->startSpan('test-span');
$span->end(); // 关键！必须调用
- 执行后 curl
http://localhost:14268/api/traces应返回 200，且 Jaeger UI 刷新后出现 service 名为test的 trace - 若返回 404，说明 Jaeger 没跑在 14268 端口，或用了 all-in-one 镜像但未加
--collector.host-port=14268 - 若返回 500，检查 Jaeger 日志是否提示
invalid span format—— 这通常是 SDK 版本与 Jaeger 版本不兼容（v1.22+ Jaeger 要求 OTLP v1.0.0+ 协议，PHP SDK v1.0.0 已适配）
真正麻烦的是跨进程 context 传递：PHP-FPM 模式下，每个请求是独立进程，$_SERVER 是唯一可靠的传播载体；Swoole 或 RoadRunner 环境则需额外处理协程间 context 绑定，SDK 目前不内置支持。
