339 lines
8.4 KiB
Markdown
339 lines
8.4 KiB
Markdown
# 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/)
|