PHP项目怎么使用Jaeger？

wen java案例 2026-07-23 2

本文目录导读：

PHP项目怎么使用Jaeger？

目录导读
为什么PHP项目需要Jaeger？
Jaeger核心概念速览
PHP集成Jaeger的三种主流方案
从零开始：安装与配置Jaeger Agent和Collector
PHP代码接入步骤（OpenTracing API + Jaeger Client）
Guzzle HTTP客户端追踪（跨服务调用链完整）
进阶技巧
常见问题与解答

PHP项目实战指南：如何高效集成Jaeger实现分布式链路追踪

目录导读

为什么PHP项目需要Jaeger？ – 分布式系统下的性能瓶颈与排查痛点
Jaeger核心概念速览 – Span、Trace、Context Propagation
PHP集成Jaeger的三种主流方案 – OpenTracing API、Jaeger PHP Client、Guzzle中间件
从零开始：安装与配置Jaeger Agent和Collector – Docker Compose快速搭建
PHP代码接入步骤 – 手动埋点与自动拦截实战
Guzzle HTTP客户端追踪 – 跨服务调用链完整打通
进阶技巧 – 采样策略、Tag与Log关联、性能影响控制
常见问题与解答 – 集成失败、Span丢失、性能下降怎么办？

为什么PHP项目需要Jaeger？

在微服务架构或大型单体PHP应用中,一次用户请求可能跨越多个服务（API Gateway、业务服务、数据库、缓存队列），传统日志只能记录单点信息，当出现延迟或错误时，你很难回答以下问题：

请求到底卡在了哪个服务？
数据库查询耗时多少？Redis调用是否拖慢整体？
某次HTTP调用失败是上游服务超时还是网络问题？

Jaeger 作为CNCF毕业的分布式追踪系统，能通过 Span 和 Trace 把整个请求链路的耗时、状态、错误信息串联起来，结合Grafana或自带的UI，你可以快速定位性能瓶颈。

问答：Jaeger vs 传统日志监控的区别？
传统日志是“点”监控，只能看到单个服务或单机情况；Jaeger是“线”监控，完整展示一次请求穿越多个服务的全路径，包括每个阶段的耗时、错误、标签信息。

Jaeger核心概念速览

在动手之前,先掌握三个关键概念：

Trace：一次完整的请求链路，由多个Span组成，每个Trace拥有唯一的Trace ID。
Span：Trace中的最小工作单元，代表一个操作（如“查询数据库”、“调用订单服务”），Span包含开始时间、结束时间、状态、Tag、Log等。
Context Propagation：上下文传播机制，将Trace ID、Span ID通过HTTP头（如uber-trace-id）或消息队列头传递到下一个服务，从而串联整条链路。

PHP集成时,需要确保每个服务都能正确提取和传递这些上下文信息。

PHP集成Jaeger的三种主流方案

方案	适用场景	优点	缺点
OpenTracing API (推荐)	新项目或统一追踪标准	与语言无关，方便切换后端	需额外安装Jaeger适配器
Jaeger PHP Client	快速接入Jaeger	官方维护，配置简单	功能相对基础，缺少插件
Guzzle Middleware	纯API调用追踪	自动拦截所有HTTP请求	仅限Guzzle6+，不支持非HTTP链路

推荐组合：使用 OpenTracing API + Jaeger PHP Client + Guzzle中间件，既能保证扩展性，又能覆盖自动追踪。

从零开始：安装与配置Jaeger Agent和Collector

使用Docker Compose快速启动Jaeger all-in-one（适合开发环境）：

version: '3'
services:
  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "6831:6831/udp"   # 接收Agent上报
      - "16686:16686"     # UI界面
      - "14268:14268"     # 接收HTTP上报
    environment:
      - COLLECTOR_ZIPKIN_HTTP_PORT=9411

启动后访问 http://localhost:16686 即可看到Jaeger UI。

PHP端无需再启动Agent，Jaeger all-in-one自带Collector功能，生产环境建议单独部署Agent和Collector集群。

PHP代码接入步骤（OpenTracing API + Jaeger Client）

1 安装依赖

composer require jaeger/jaeger
composer require opentracing/opentracing

2 初始化Tracer（在入口文件如 index.php）

use Jaeger\Config;
// 配置Jaeger
$config = Config::getInstance();
$config->gen128bit(); // 生成128位Trace ID
$config->flushBufferSize(100);
$tracer = $config->initTracer('your-service-name', '0.0.0.0', 6831);
// 设置全局Tracer（方便在任何地方调用）
OpenTracing\GlobalTracer::set($tracer);

3 手动埋点示例（处理订单请求）

// 假设你有一个处理下单的函数
function createOrder($userId, $productId) {
    $span = OpenTracing\GlobalTracer::get()->startActiveSpan('createOrder'); 
    $scope = $span->getScope();
    try {
        // 设置标签
        $scope->getSpan()->setTag('user.id', $userId);
        $scope->getSpan()->setTag('product.id', $productId);
        // 模拟数据库查询
        $dbSpan = OpenTracing\GlobalTracer::get()->startActiveSpan('query.database');
        usleep(rand(10000, 50000)); // 模拟50ms延迟
        $dbSpan->close();
        // 模拟调用另一个服务
        $httpSpan = OpenTracing\GlobalTracer::get()->startActiveSpan('call.inventory');
        usleep(rand(20000, 80000));
        $httpSpan->close();
    } catch (\Exception $e) {
        $scope->getSpan()->log(['event' => 'error', 'message' => $e->getMessage()]);
        $scope->getSpan()->setTag('error', true);
    } finally {
        $scope->close();
    }
}

关键点：每个Span完成或异常后必须调用close()，否则Jaeger无法收到完整数据，推荐使用try...finally确保关闭。

问答：Span不显示在Jaeger UI中怎么办？
检查Agent端口（6831）是否可连通；确认PHP脚本结束后调用了$tracer->flush()；查看PHP错误日志中是否有“Failed to send span”字样。

Guzzle HTTP客户端追踪（跨服务调用链完整）

PHP项目中80%的跨服务调用通过HTTP，使用Guzzle中间件自动为每个请求注入Jaeger上下文并创建子Span：

use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;
use OpenTracing\GlobalTracer;
function createTracedGuzzleClient() {
    $tracer = GlobalTracer::get();
    $handlerStack = HandlerStack::create();
    $handlerStack->push(function (callable $handler) use ($tracer) {
        return function ($request, array $options) use ($handler, $tracer) {
            // 创建一个追踪该HTTP请求的Span
            $span = $tracer->startActiveSpan('http.request');
            $scope = $span->getScope();
            // 注入Jaeger头
            $tracer->inject($scope->getSpan()->getContext(), 
                OpenTracing\Formats\TEXT_MAP, 
                $request->getHeaders()
            );
            // 发送请求并记录结果
            $response = $handler($request, $options);
            $scope->getSpan()->setTag('http.method', $request->getMethod());
            $scope->getSpan()->setTag('http.url', (string)$request->getUri());
            $scope->getSpan()->setTag('http.status_code', $response->getStatusCode());
            $scope->close();
            return $response;
        };
    });
    return new Client(['handler' => $handlerStack, 'verify' => false]);
}
// 使用方式
$client = createTracedGuzzleClient();
$response = $client->get('http://inventory-service/api/check-stock');

在目标服务（如inventory-service）中，必须同样集成Jaeger并提取uber-trace-id头，否则链路会在此断开。

进阶技巧

1 采样策略

生产环境不要100%采样，避免性能开销，通过环境变量控制：

$config->setSamplerType(\Jaeger\SAMPLER_TYPE_RATIO);
$config->setSamplerRate(0.1); // 10%采样

2 与业务日志关联

在Span中添加自定义Tag或Log,方便在Jaeger UI中搜索：

$span->log(['event' => 'cache_hit', 'key' => $cacheKey]);
$span->setTag('db.table', 'orders');

3 性能影响控制

设置flushBufferSize（比如500）减少UDP发送次数。
使用异步上报（修改Jaeger\Reporter\RemoteReporter的maxQueueSize）。
只在关键业务路径埋点,避免在循环中创建大量Span。

常见问题与解答

Q1：Jaeger UI中看不到刚刚的Trace，但代码没有报错？
A：检查Jaeger UI时间范围是否正确（默认只显示最近1小时）；确认Tracer在脚本结束前已flush；用tcpdump抓包确认UDP包是否发到6831端口。

Q2：Span显示在错误的Service下，如何指定服务名？
A：在initTracer()的第一个参数设置服务名，该名称会出现在Jaeger UI的“Service”下拉菜单中，如果忘记设置，默认服务名可能是“php-app”。

Q3：如何追踪RabbitMQ/Redis操作？
A：手动创建子Span并注入上下文，例如Redis调用前调用startActiveSpan('redis.get')，完成后close()，对于MQ，需要将Trace ID放入消息头。

Q4：Jaeger Agent和Collector有什么不同？我该用哪个？
A：Agent是轻量级代理，通常部署在每台服务器上，负责接收Span数据并批量发送给Collector，Collector负责存储和查询，开发环境用all-in-one即可，生产环境建议分开部署。

Q5：OpenTracing API和OpenTelemetry API哪个更好？
A：OpenTracing已停止更新，但Jaeger仍支持该标准，新项目建议直接使用OpenTelemetry（Jaeger也兼容），但PHP的OpenTelemetry库目前成熟度不如Jaeger原生客户端，对于现有PHP项目，Jaeger PHP Client仍是稳定选择。

通过以上步骤,你可以将Jaeger无缝集成到任何PHP项目中，核心要点：初始化全局Tracer → 手动或自动埋点 → 在跨服务调用时注入上下文 → 合理设置采样策略，一旦接入成功，你将拥有可视化分布式调用链，大幅降低定位复杂问题的难度。

建议：先在开发环境完整的跑一遍上述流程，确认Span能正常上报至Jaeger UI ，再逐步应用于生产环境的关键服务。

（全文完）