# TYAPI 项目链路追踪指南

## 概述

本项目使用 **Jaeger** 进行分布式链路追踪，通过 **OpenTelemetry** 标准实现数据收集，并在 **Grafana** 中进行可视化展示。

## 架构说明

```
应用程序 -> OpenTelemetry -> Jaeger -> Grafana 可视化
```

-   **应用程序**：使用 OpenTelemetry Go SDK 生成链路追踪数据
-   **Jaeger**：收集、存储和查询链路追踪数据
-   **Grafana**：提供链路追踪数据的可视化界面

## 快速启动

### 1. 启动基础设施服务

```bash
# 启动所有服务（包括Jaeger）
docker-compose -f docker-compose.dev.yml up -d

# 检查服务状态
docker-compose -f docker-compose.dev.yml ps
```

### 2. 验证服务启动

-   **Jaeger UI**: http://localhost:16686
-   **Grafana**: http://localhost:3000 (admin/Gf7nB3xM9cV6pQ2w)
-   **应用程序**: http://localhost:8080

### 3. 启动应用程序

```bash
# 确保配置正确
make run
```

## 配置说明

### 应用配置（config.yaml）

```yaml
monitoring:
    metrics_enabled: true
    metrics_port: "9090"
    tracing_enabled: true # 启用链路追踪
    tracing_endpoint: "http://localhost:4317" # OTLP gRPC 端点
    sample_rate: 0.1 # 采样率：10%
```

### Jaeger 配置

-   **UI 端口**: 16686
-   **OTLP gRPC**: 4317
-   **OTLP HTTP**: 4318
-   **传统 gRPC**: 14250
-   **传统 HTTP**: 14268

### 采样策略

项目使用智能采样策略（配置在 `deployments/docker/jaeger-sampling.json`）：

-   **默认采样率**: 10%
-   **健康检查接口**: 1%（减少噪音）
-   **关键业务接口**: 50%（如注册、登录）
-   **错误请求**: 100%（所有 4xx 和 5xx 错误）

#### 错误优先采样

系统实现了错误优先采样策略，确保所有出现错误的请求都被 100%采样记录，即使它们不在高采样率的关键业务接口中。这包括：

-   所有返回 4xx 状态码的客户端错误（如 404、400、403 等）
-   所有返回 5xx 状态码的服务器错误（如 500、503 等）
-   所有抛出异常的数据库操作
-   所有失败的缓存操作
-   所有失败的外部 API 调用

这种策略确保了在出现问题时，相关的链路追踪数据始终可用，便于问题排查和根因分析。

## 使用指南

### 在 Grafana 中查看链路追踪

1. **访问 Grafana**: http://localhost:3000
2. **登录**: admin / Gf7nB3xM9cV6pQ2w
3. **导航**: Dashboard → TYAPI 链路追踪监控
4. **数据源**:
    - Jaeger 数据源已自动配置
    - URL: http://jaeger:16686

### 在 Jaeger UI 中查看链路追踪

1. **访问 Jaeger**: http://localhost:16686
2. **选择服务**: TYAPI Server
3. **查询追踪**:
    - 按时间范围筛选
    - 按操作类型筛选
    - 按标签筛选
    - 按错误状态筛选（使用标签`error=true`）

### 生成测试数据

```bash
# 注册用户（会生成链路追踪数据）
curl -X POST http://localhost:8080/api/v1/users/send-sms \
  -H "Content-Type: application/json" \
  -d '{"phone": "13800138000"}'

# 用户注册
curl -X POST http://localhost:8080/api/v1/users/register \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "13800138000",
    "password": "Test123456",
    "sms_code": "123456"
  }'

# 用户登录
curl -X POST http://localhost:8080/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "13800138000",
    "password": "Test123456"
  }'

# 生成错误请求（测试错误采样）
curl -X GET http://localhost:8080/api/v1/not-exist-path
```

## 链路追踪功能特性

### 自动追踪的操作

1. **HTTP 请求**: 所有入站 HTTP 请求
2. **数据库查询**: GORM 操作
3. **缓存操作**: Redis 读写
4. **外部调用**: 短信服务等
5. **业务逻辑**: 用户注册、登录等

### 追踪数据包含的信息

-   **请求信息**: URL、HTTP 方法、状态码
-   **时间信息**: 开始时间、持续时间
-   **错误信息**: 异常堆栈和错误消息
-   **上下文信息**: TraceID、SpanID
-   **自定义标签**: 服务名、操作类型等

### TraceID 传播

应用程序会在 HTTP 响应头中返回 TraceID：

```
X-Trace-ID: 4bf92f3577b34da6a3ce929d0e0e4736
```

通过这个 ID，可以在日志系统和 Jaeger UI 中关联同一请求的所有信息。

## 错误追踪与分析

### 错误链路的查询

在 Jaeger UI 中，可以通过以下方式查询错误链路：

1. 在查询界面选择"Tags"标签
2. 添加条件：`error=true`或`operation.type=error`
3. 点击"Find Traces"按钮

这将显示所有被标记为错误的链路追踪数据，包括：

-   所有 HTTP 4xx/5xx 错误
-   所有数据库操作错误
-   所有缓存操作错误
-   所有外部 API 调用错误

### 错误根因分析

链路追踪系统记录了错误发生的完整上下文，包括：

-   错误发生的具体操作
-   错误的详细信息和堆栈
-   错误发生前的所有操作序列
-   相关的请求参数和环境信息

通过这些信息，可以快速定位问题根源，而不需要在多个日志文件中搜索。

## 性能优化建议

### 采样率配置

-   **开发环境**: 10-50%（便于调试）
-   **测试环境**: 5-10%
-   **生产环境**: 1-5%（减少性能影响）
-   **错误请求**: 始终保持 100%（所有环境）

### 批处理配置

生产环境建议使用批处理导出器：

```yaml
monitoring:
    tracing_enabled: true
    tracing_endpoint: "http://jaeger:4317"
    sample_rate: 0.01 # 生产环境1%采样率
```

## 故障排除

### 常见问题

1. **链路追踪数据未显示**

    - 检查应用配置中 `tracing_enabled: true`
    - 确认 Jaeger 服务正常运行
    - 检查网络连接和端口

2. **Grafana 无法连接 Jaeger**

    - 确认 Jaeger 数据源配置正确
    - 检查容器网络连接
    - 验证 Jaeger UI 可访问

3. **性能影响过大**

    - 降低采样率
    - 检查批处理配置
    - 监控内存和 CPU 使用率

4. **错误请求未被 100%采样**
    - 检查 Jaeger 采样配置中是否包含`"operation": "error"`的配置
    - 确认中间件正确设置了错误标记
    - 验证错误处理逻辑是否正确调用了`SetSpanError`方法

### 调试命令

```bash
# 检查Jaeger健康状态
curl http://localhost:14269/health

# 检查容器日志
docker logs tyapi-jaeger

# 检查应用追踪配置
curl http://localhost:8080/health
```

## 监控仪表板

### 默认仪表板

项目提供了预配置的 Grafana 仪表板：

-   **TYAPI 链路追踪监控**: 展示追踪概览和关键指标
-   **HTTP 请求分析**: 请求速率和延迟分布
-   **服务依赖图**: 服务间调用关系
-   **错误分析**: 错误率和错误类型分布

### 自定义仪表板

可以根据业务需求创建自定义仪表板：

1. 在 Grafana 中创建新仪表板
2. 添加 Jaeger 查询面板
3. 配置告警规则
4. 导出仪表板配置

## 生产环境部署

### 环境变量配置

```bash
export JAEGER_ENDPOINT="http://jaeger:4317"
export TRACING_SAMPLE_RATE="0.01"
```

### Kubernetes 部署

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
    name: app-config
data:
    config.yaml: |
        monitoring:
          tracing_enabled: true
          tracing_endpoint: "http://jaeger-collector:4317"
          sample_rate: 0.01
```

## 扩展功能

### 自定义追踪

```go
// 在业务代码中添加自定义追踪
ctx, span := tracer.StartSpan(ctx, "custom-operation")
defer span.End()

// 添加自定义属性
tracer.AddSpanAttributes(span,
    attribute.String("user.id", userID),
    attribute.String("operation.type", "business"),
)

// 记录错误
if err != nil {
    tracer.SetSpanError(span, err)
}
```

### 业务指标集成

链路追踪数据可以与业务指标结合：

-   用户行为分析
-   性能瓶颈定位
-   错误率监控
-   服务依赖分析

## 最佳实践

1. **合理设置采样率**: 平衡数据完整性和性能影响
2. **添加有意义的标签**: 便于后续查询和分析
3. **处理敏感信息**: 避免在追踪数据中记录密码等敏感信息
4. **监控存储空间**: 定期清理过期的追踪数据
5. **设置告警规则**: 对异常追踪模式设置告警
6. **错误优先采样**: 确保所有错误请求都被记录，无论采样率如何
7. **关联日志系统**: 在日志中包含 TraceID，便于关联查询

## 参考资料

-   [OpenTelemetry Go 文档](https://opentelemetry.io/docs/instrumentation/go/)
-   [Jaeger 官方文档](https://www.jaegertracing.io/docs/)
-   [Grafana Jaeger 数据源](https://grafana.com/docs/grafana/latest/datasources/jaeger/)