如何在 PHP 中通过Composer安装 PHP-OpenTelemetry 库实现分布式链路追踪-composer-PHP中文网

composer 安装 php-opentelemetry 失败是因为官方未发布 open-telemetry/opentelemetry 包，仅提供 open-telemetry/sdk:^1.0（php 8.1+），需手动配置 jaeger/zipkin exporter 并调用 $span->end()。

如何在 php 中通过composer安装 php-opentelemetry 库实现分布式链路追踪

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 应用启动时初始化；不建议在每次请求中重复创建。

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。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

容易踩的坑：在中间件或路由处理函数里直接 $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 目前不内置支持。