# 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-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FiberPHP Tracing

基于 [Zipkin](https://zipkin.io/) 的分布式链路追踪包，为 FiberPHP 框架提供 HTTP、MySQL、Redis 等组件的自动埋点能力。

## 特性

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

## 环境要求

- PHP >= 8.3
- `ext-json`
- `openzipkin/zipkin` ^3.0
- `fiberphp/contract`、`fiberphp/container`、`fiberphp/http`、`fiberphp/redis` dev-master
- `fiberphp/framework`（suggest，运行环境）或 `fiberphp/database`（suggest，MySQL 追踪）

## 安装

```bash
composer require fiberphp/tracing
```

安装后自动完成：

- 包内置 `config/tracing.php` 默认配置随包自动合并（装包即用，应用 `config/tracing.php` 同名键覆盖）
- 通过 `TracingProvider` 注册（两阶段：register + boot），由 PackageManifest 自动发现
- 追加 `TraceMiddleware` 到中间件链

## 配置

`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' => (float) env('ZIPKIN_SAMPLE_RATIO', 1),

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

    // 组件开关
    'components' => [
        'mysql' => true,
        'redis' => 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 请求（自动）

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

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

### MySQL（自动）

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

### Redis

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

### HTTP 外调

```php
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（开发环境）

```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`
- **Redis 追踪**：`ping`/`auth`/`select` 等内部命令不追踪
- **MySQL 追踪**：心跳检测 SQL 不追踪