# tracing **Repository Path**: fiberphp/tracing ## Basic Information - **Project Name**: tracing - **Description**: 🔍 FiberPHP 分布式追踪组件 —— 基于 Zipkin,支持 HTTP/数据库/RPC 自动埋点,协程非阻塞,开箱即用。 - **Primary Language**: PHP - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-22 - **Last Updated**: 2026-11-09 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # FiberPHP Tracing 基于 [Zipkin](https://zipkin.io/) 的分布式链路追踪包,为 FiberPHP 应用提供 HTTP 请求与数据库查询的自动埋点能力。 ## 特性 - **HTTP 请求追踪**:中间件创建 Server Span,提取/注入 B3 传播头 - **数据库查询追踪**:监听 `QueryEvent` / `QueryErrorEvent` 记录 SQL 耗时与错误 - **HTTP 外调透传**:`Propagation` 辅助类创建 Client Span 并注入 B3 头 - **日志关联**:自动将 `trace_id` / `span_id` 写入协程 Context - **协程安全**:基于 `FiberPHP\Context` 实现协程级 Span 隔离 - **采样控制**:按概率采样,未采样时零开销 ## 环境要求 - PHP >= 8.5 - `ext-json` - `openzipkin/zipkin` ^3.0 - `fiberphp/framework`、`fiberphp/container`、`fiberphp/event` 可选依赖(缺失时对应能力自动跳过): - `fiberphp/http` —— `TraceMiddleware` 提供 HTTP 请求入口追踪 - `fiberphp/database` —— 数据库查询 Span 监听 ## 安装 ```bash composer require fiberphp/tracing ``` 在应用 `config/app.php` 的 `providers` 数组中显式注册服务提供者: ```php 'providers' => [ \FiberPHP\Tracing\TracingProvider::class, // ... ], ``` 配置通过包发布机制拷贝到应用 `config/tracing.php`(`pathRelation` 声明)。 ## 配置 `config/tracing.php`: ```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' => env('ZIPKIN_SAMPLE_RATIO', 1.0), // 上报超时(秒) 'timeout' => env('ZIPKIN_TIMEOUT', 5.0), // 组件开关 'components' => [ 'mysql' => true, 'http' => true, ], ]; ``` `.env` 示例: ```env ZIPKIN_ENABLE=true ZIPKIN_ENDPOINT=http://localhost:9411/api/v2/spans ZIPKIN_SERVICE_NAME=fiberphp ZIPKIN_SAMPLE_RATIO=1 ``` ## 使用方式 ### HTTP 请求 在 `config/http.php` 的全局中间件列表中追加: ```php 'middleware' => [ \FiberPHP\Tracing\Middleware\TraceMiddleware::class, // ... ], ``` `TraceMiddleware` 会提取上游 B3 传播头、创建 Server Span、记录请求标签,并在响应头回写 `X-Trace-Id`。 ### 数据库查询 `TracingProvider` 启动时注册 `QueryEvent` / `QueryErrorEvent` 监听器,自动记录每条 SQL 的耗时、语句、连接名与错误。 ### HTTP 外调 ```php use FiberPHP\Tracing\Http\Propagation; ['span' => $span, 'headers' => $headers] = Propagation::start('GET', 'https://api.example.com'); $response = $httpClient->get('https://api.example.com', ['headers' => $headers]); Propagation::finish($span, $response->getStatusCode()); ``` ### 独立使用 不安装 `fiberphp/config` 时可直接注入配置: ```php use FiberPHP\Tracing\Tracer; Tracer::configure(['enable' => true, 'service_name' => 'demo', 'endpoint' => 'http://localhost:9411/api/v2/spans']); ``` ## 调用链示例 ``` GET /api/order [──────────────────────] 120ms ├─ mysql.query SELECT * FROM... [──] 8ms ├─ mysql.query SELECT * FROM... [─] 2ms ├─ http.get api.example.com [────────] 85ms └─ mysql.query UPDATE orders ... [─] 3ms ``` ## 部署 Zipkin Server ### Docker(开发环境) ```bash 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`