feat(架构): 完善基础架构设计
This commit is contained in:
338
docs/开始指南/链路追踪指南.md
Normal file
338
docs/开始指南/链路追踪指南.md
Normal file
@@ -0,0 +1,338 @@
|
||||
# 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/)
|
||||
Reference in New Issue
Block a user