README

基于 Zipkin 的分布式链路追踪包，为 FiberPHP 框架提供 HTTP、MySQL、Redis 等组件的自动埋点能力。

特性

HTTP 请求追踪：全局中间件自动创建 Server Span，提取/注入 B3 传播头
MySQL 追踪：通过 Db::listen() 钩子零侵入记录 SQL 执行
Redis 追踪：TracingSync / TracingAsync 包装类自动记录命令执行
HTTP 外调透传：Propagation 辅助类注入 B3 头到下游请求
日志关联：自动将 trace_id / span_id 注入日志上下文
协程安全：基于 FiberPHP\Context 实现协程级 Span 隔离
采样控制：按概率采样，未采样时零开销
自动安装：安装时自动注册 Provider 和 Middleware

环境要求

PHP >= 8.3
ext-json
openzipkin/zipkin ^3.0
fiberphp/framework dev-master

安装

composer require fiberphp/tracing

安装后自动完成：

复制配置文件到 config/tracing.php
通过 TracingProvider 注册（两阶段：register + boot），由 PackageManifest 自动发现
追加 TraceMiddleware 到中间件链

配置

config/tracing.php：

return [
    'enable' => env('ZIPKIN_ENABLE', false),

    // Zipkin Server 上报地址
    // 自建：http://localhost:9411/api/v2/spans
    // ARMS：https://{arms-endpoint}/api/v2/spans
    'endpoint' => env('ZIPKIN_ENDPOINT', 'http://localhost:9411/api/v2/spans'),

    // 服务名称
    'service_name' => env('ZIPKIN_SERVICE_NAME', 'fiberphp'),

    // 采样率（0~1，1 = 全采样）
    'sample_ratio' => (float) env('ZIPKIN_SAMPLE_RATIO', 1),

    // 上报超时（秒）
    'timeout' => (float) env('ZIPKIN_TIMEOUT', 5),

    // 组件开关
    'components' => [
        'mysql' => true,
        'redis' => true,
        'http'  => true,
    ],
];

.env 示例：

ZIPKIN_ENABLE=true
ZIPKIN_ENDPOINT=http://localhost:9411/api/v2/spans
ZIPKIN_SERVICE_NAME=fiberphp
ZIPKIN_SAMPLE_RATIO=1

使用方式

HTTP 请求（自动）

安装后自动生效，无需手动代码。TraceMiddleware 会：

从请求头提取 B3 传播上下文（X-B3-TraceId 等）
创建 Server Span
请求完成后结束 Span 并上报
响应头回传 X-Trace-Id

MySQL（自动）

TracingProvider 启动时通过 Db::listen() 注册监听器，自动记录每条 SQL 的执行耗时、语句、连接名。

Redis

TracingProvider 启动时自动将 Redis 客户端替换为追踪版本，无需手动修改代码。

HTTP 外调

use FiberPHP\Tracing\Http\Propagation;

// 开始追踪
['span' => $span, 'headers' => $headers] = Propagation::start('GET', 'https://api.example.com');

// 发起请求时注入 B3 头
$response = $httpClient->get('https://api.example.com', [
    'headers' => $headers,
]);

// 结束追踪
Propagation::finish($span, $response->getStatusCode());

调用链示例

GET /api/order                    [──────────────────────] 120ms
├─ mysql.query SELECT * FROM...   [──] 8ms
├─ redis.get order:123            [─] 1ms
├─ http.get api.example.com       [────────] 85ms
└─ redis.set order:123            [─] 1ms

部署 Zipkin Server

Docker（开发环境）

docker run -d --name zipkin -p 9411:9411 openzipkin/zipkin

访问 http://localhost:9411 查看 Zipkin UI。

阿里云 ARMS（生产环境）

ARMS 兼容 Zipkin 协议，在控制台开通「链路追踪 Tracing Analysis」后获取上报端点，填入 ZIPKIN_ENDPOINT。

注意事项

未启用时（ZIPKIN_ENABLE=false），所有追踪操作降级为 no-op，零性能开销
采样率：生产环境建议 0.05~0.1，开发环境设为 1
Redis 追踪：ping/auth/select 等内部命令不追踪
MySQL 追踪：心跳检测 SQL 不追踪

fiberphp / tracing

Maintainers

Package info

Statistics

Security