kami_gateway/.qoder/repowiki/zh/content/监控与故障排除.md

监控与故障排除

**本文档引用的文件** - [logs.go](file://internal/otelTrace/logs.go) - [init.go](file://internal/otelTrace/init.go) - [middleware.go](file://internal/otelTrace/middleware.go) - [simple.go](file://internal/otelTrace/simple.go) - [consts.go](file://internal/otelTrace/consts.go) - [utils.go](file://internal/otelTrace/utils.go) - [span.go](file://internal/otelTrace/span.go) - [pay_solve_test.go](file://internal/service/pay_solve_test.go) - [payfor_solve.go](file://internal/service/pay_for/payfor_solve.go) - [pay_service.go](file://internal/service/pay_service.go) - [order_controller.go](file://internal/controllers/order_controller.go) - [router.go](file://internal/routers/router.go) - [metrics.go](file://internal/service/supplier/third_party/pool/metrics.go)

目录

1. 分布式追踪
2. 日志诊断
3. 关键指标与Prometheus集成
4. 常见问题排查
5. 性能监控与优化
6. 告警配置

分布式追踪

本系统使用OpenTelemetry（otelTrace包）实现分布式追踪，通过otelTrace.InitTracer() 函数初始化追踪器，配置了生产环境优化的Trace导出器、资源标识、采样策略和批量处理器。追踪器使用gRPC协议将数据发送到指定的收集器，支持gzip压缩以减少网络传输量。

系统通过otelTrace.Middleware中间件实现请求级别的追踪。该中间件在请求处理开始时创建一个Span，从请求头中提取上游的trace context，并注入到当前context中。Span记录了HTTP方法、URL、状态码、响应大小、处理时长等关键性能指标。当请求处理时间超过5秒时，会自动标记为慢请求并记录警告日志。

sequenceDiagram
participant Client as "客户端"
participant Middleware as "追踪中间件"
participant Span as "Span"
participant Exporter as "导出器"
Client->>Middleware : 发起HTTP请求
Middleware->>Span : 创建Span并提取上下文
Span->>Span : 记录HTTP基础信息
Middleware->>Client : 处理业务逻辑
Span->>Span : 记录响应状态码和处理时长
Span->>Exporter : 结束Span并导出
Exporter->>Collector : 发送追踪数据

Diagram sources

• init.go
• middleware.go

Section sources

• init.go
• middleware.go

日志诊断

系统使用otelTrace.Logger进行日志记录，该Logger集成了OpenTelemetry的日志导出功能。日志信息不仅会输出到标准输出，还会通过OTLP协议发送到日志收集器，实现日志的集中管理和分析。

otelTrace.logs.go文件定义了CustomLogger结构体，它包装了Zap日志库，并提供了WithContext 方法，可以将OpenTelemetry的context与日志记录关联起来。这使得在查看日志时，可以轻松地关联到相应的追踪信息，实现日志与追踪的联动分析。

classDiagram
class CustomLogger {
+logger *zap.Logger
+WithContext(ctx context.Context) *zap.Logger
}
class Logger {
+CustomLogger
}
Logger --> CustomLogger : "全局实例"

Diagram sources

• logs.go
• init.go

Section sources

• logs.go
• init.go

关键指标与Prometheus集成

系统通过otelTrace.InitTracer()函数配置了Metrics导出器，将关键指标通过OTLP协议发送到收集器。同时， internal/service/supplier/third_party/pool/metrics.go文件定义了Metrics结构体，用于监控订单处理相关的指标。

这些指标包括：

• order_pool_processed_total: 已处理的订单总数
• order_pool_failed_total: 处理失败的订单总数
• order_pool_processing_seconds: 订单处理时间分布
• order_pool_size: 当前订单池大小
• order_queue_length: 当前订单队列长度
• order_query_seconds: 订单查询时间分布
• order_query_failed_total: 订单查询失败总数

flowchart TD
A[业务代码] --> B[记录指标]
B --> C{指标类型}
C --> |计数器| D[OrderProcessed]
C --> |计数器| E[OrderFailed]
C --> |直方图| F[ProcessingTime]
C --> |仪表盘| G[PoolSize]
C --> |仪表盘| H[OrderQueueLength]
D --> I[Prometheus]
E --> I
F --> I
G --> I
H --> I
I --> J[监控面板]

Diagram sources

• init.go
• metrics.go

Section sources

• init.go
• metrics.go

常见问题排查

支付请求超时

当支付请求超时时，首先检查otelTrace.Middleware中记录的Span，查看处理时长是否超过5秒。如果超过，说明存在慢请求。可以通过以下步骤排查：

1. 检查数据库连接池是否耗尽，查看order_pool_size和order_queue_length指标。
2. 检查Redis连接是否正常，查看TotalRedisErrors指标。
3. 检查上游供应商接口是否响应缓慢，查看order_query_seconds指标。

回调失败

当回调失败时，首先检查order_controller.go中的OrderUpdate方法。该方法处理手动修正订单状态的请求。可以通过以下步骤排查：

1. 检查bankOrderId是否正确，通过order.GetOrderByBankOrderId查询订单信息。
2. 检查solveType是否正确，确保是SUCCESS或FAIL。
3. 检查service.SolvePaySuccess或service.SolvePayFail方法的执行结果。

数据库连接池耗尽

当数据库连接池耗尽时，系统会记录相关错误日志。可以通过以下步骤排查：

1. 检查otelTrace.Logger中的错误日志，查找database connection pool exhausted等关键词。
2. 检查order_pool_size和order_queue_length指标，查看订单池和队列的大小。
3. 检查CurrentChannelConcurrency、CurrentRoadConcurrency和CurrentFaceValueConcurrency指标，查看当前并发数。

Section sources

• order_controller.go
• payfor_solve.go
• pay_service.go

性能监控与优化

系统通过otelTrace.Middleware和Metrics结构体实现了全面的性能监控。关键性能指标包括HTTP响应时间、订单处理时间、数据库查询时间等。

对于慢查询的识别，系统在otelTrace.Middleware中设置了5秒的阈值。当请求处理时间超过5秒时，会自动记录警告日志，并标记为慢请求。开发者可以通过分析这些日志，定位性能瓶颈。

优化建议：

1. 优化数据库查询，添加必要的索引。
2. 使用缓存减少数据库访问。
3. 优化上游供应商接口调用，减少网络延迟。
4. 调整订单池大小和队列长度，平衡性能和资源使用。

Section sources

• middleware.go
• metrics.go

告警配置

系统通过otelTrace.monitorExporterHealth函数实现了导出器健康状态的监控。该函数每30秒检查一次导出失败次数，如果失败次数超过10次，会记录警告日志。

告警规则建议：

1. 当exportFailures超过10次时，发送告警通知。
2. 当order_query_failed_total在5分钟内增加超过100次时，发送告警通知。
3. 当order_pool_processing_seconds的95分位数超过5秒时，发送告警通知。
4. 当order_pool_size接近最大值时，发送告警通知。

Section sources

• utils.go
• metrics.go