# 请求追踪 (Tracing)

URL: https://caijiao.org/pingora/tracing
Source: docs/pingora/tracing.md
Description: 学习如何在 Pingora 中启用请求追踪，实现分布式请求监控、性能分析和调试。

Pingora 支持 **请求追踪（Tracing）**，可以记录请求在各阶段的执行情况，帮助开发者分析性能瓶颈和排查问题。

## 启用请求追踪

在配置文件中启用 tracing 模块：

```yaml
tracing:
  enable: true
  level: debug
  output: stdout
````

* `enable`：是否启用追踪
* `level`：追踪日志级别（debug/info/warn）
* `output`：日志输出目标，可为控制台或文件

## 使用示例

```rust
use pingora::tracing::trace;

fn pre_filter(req: &Request, ctx: &mut Context) -> Result<(), Error> {
    trace!("请求 {} 进入前置过滤器", req.path());
    Ok(())
}

fn response_filter(_req: &Request, ctx: &mut Context) -> Result<(), Error> {
    trace!("响应阶段执行完毕");
    Ok(())
}
```

* `trace!` 宏记录请求执行信息
* 可在不同阶段标记关键操作

## 分布式请求追踪

* Pingora 可集成 OpenTelemetry 或 Jaeger
* 每个请求生成唯一 trace_id
* 支持跨服务链路追踪，便于定位性能瓶颈

### 示例（OpenTelemetry 集成）

```rust
use opentelemetry::global;
use tracing_opentelemetry::OpenTelemetryLayer;
use tracing_subscriber::Registry;

let tracer = opentelemetry_jaeger::new_pipeline()
    .with_service_name("pingora")
    .install_simple()
    .unwrap();

let telemetry = OpenTelemetryLayer::new(tracer);
let subscriber = Registry::default().with(telemetry);
tracing::subscriber::set_global_default(subscriber).unwrap();
```

## 应用场景

1. **性能分析**：追踪请求耗时，识别瓶颈
2. **调试**：记录请求路径、上下文状态和错误信息
3. **监控**：结合 Prometheus 或 Jaeger 进行可视化监控

---

通过请求追踪功能，Pingora 可以提供完整的请求生命周期监控，帮助开发者快速定位问题、优化性能和提升服务质量。