team/tyapi-server

Fork 0

Files

liangzai 5b4392894f feat(架构): 完善基础架构设计

2025-07-02 16:17:59 +08:00

8.4 KiB

Raw Blame History

TYAPI 项目链路追踪指南

概述

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

架构说明

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

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

快速启动

1. 启动基础设施服务

# 启动所有服务（包括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. 启动应用程序

# 确保配置正确
make run

配置说明

应用配置（config.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 中查看链路追踪

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

在 Jaeger UI 中查看链路追踪

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

生成测试数据

# 注册用户（会生成链路追踪数据）
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

链路追踪功能特性

自动追踪的操作

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

追踪数据包含的信息

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

TraceID 传播

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

X-Trace-ID: 4bf92f3577b34da6a3ce929d0e0e4736

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

错误追踪与分析

错误链路的查询

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

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

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

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

错误根因分析

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

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

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

性能优化建议

采样率配置

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

批处理配置

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

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

故障排除

常见问题

链路追踪数据未显示
- 检查应用配置中 tracing_enabled: true
- 确认 Jaeger 服务正常运行
- 检查网络连接和端口
Grafana 无法连接 Jaeger
- 确认 Jaeger 数据源配置正确
- 检查容器网络连接
- 验证 Jaeger UI 可访问
性能影响过大
- 降低采样率
- 检查批处理配置
- 监控内存和 CPU 使用率
错误请求未被 100%采样
- 检查 Jaeger 采样配置中是否包含"operation": "error"的配置
- 确认中间件正确设置了错误标记
- 验证错误处理逻辑是否正确调用了SetSpanError方法

调试命令

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

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

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

监控仪表板

默认仪表板

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

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

自定义仪表板

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

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

生产环境部署

环境变量配置

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

Kubernetes 部署

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

扩展功能

自定义追踪

// 在业务代码中添加自定义追踪
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)
}

业务指标集成

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

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

最佳实践

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

8.4 KiB Raw Blame History Unescape Escape