# 日志与监控

<cite>
**本文档引用的文件**
- [cmd.go](file://internal/cmd/cmd.go)
- [monitor.go](file://api/monitor/monitor.go)
- [heathcheck.go](file://api/monitor/v1/heathcheck.go)
- [monitor.go](file://internal/controller/monitor/monitor.go)
- [monitor_new.go](file://internal/controller/monitor/monitor_new.go)
- [monitor_v1_health_check.go](file://internal/controller/monitor/monitor_v1_health_check.go)
- [config.go](file://utility/otel/config.go)
- [manager.go](file://utility/otel/manager.go)
- [handler.go](file://utility/otel/handler.go)
- [utils.go](file://utility/otel/utils.go)
- [monitor.go](file://utility/monitor/monitor.go)
- [order_create.go](file://internal/logic/jd_cookie/order_create.go)
- [order_utils.go](file://internal/logic/jd_cookie/order_utils.go)
- [client.go](file://utility/integration/originalJd/client.go)
- [order_jd.go](file://internal/logic/jd_cookie/order_jd.go)
</cite>

## 更新摘要
**已做更改**
- 根据最新代码重构了OpenTelemetry集成架构描述
- 更新了监控功能实现章节以反映实际代码结构
- 修正了日志系统配置流程图与代码逻辑的一致性
- 增强了健康检查机制的技术细节说明
- 补充了命令行监控选项的实现原理
- 新增了京东订单创建、支付状态检查和卡密提取功能的日志记录说明
- 更新了苹果权益充值接口的日志记录实践

## 目录
1. [简介](#简介)
2. [OpenTelemetry集成架构](#opentelemetry集成架构)
3. [监控功能实现](#监控功能实现)
4. [日志系统配置](#日志系统配置)
5. [健康检查机制](#健康检查机制)
6. [命令行监控选项](#命令行监控选项)
7. [关键性能指标(KPI)](#关键性能指标kpi)
8. [监控数据可视化与告警](#监控数据可视化与告警)
9. [性能监控最佳实践](#性能监控最佳实践)
10. [运维诊断指南](#运维诊断指南)

## 简介

kami_backend系统通过OpenTelemetry实现了全面的分布式追踪、指标收集和日志聚合功能。本系统集成了OpenTelemetry的三大核心组件：追踪(
Tracing)、指标(Metrics)和日志(Logging)
，为系统的可观测性提供了坚实的基础。监控系统不仅提供了实时的健康检查功能，还通过命令行选项实现了灵活的监控任务管理。系统采用结构化日志格式，支持多级别日志记录，并通过配置化的存储策略确保日志数据的可靠性和可访问性。近期更新增强了京东订单处理和苹果权益充值接口的日志记录，确保敏感信息不被泄露，同时完善了错误处理日志格式。

## OpenTelemetry集成架构

```mermaid
graph TD
subgraph "kami_backend应用"
A[HTTP服务器] --> B[OTel管理器]
C[业务逻辑] --> B
D[定时任务] --> B
end
subgraph "OTel组件"
B[OTel管理器] --> E[追踪提供者]
B --> F[日志提供者]
B --> G[指标提供者]
end
E --> H[OTLP追踪导出器]
F --> I[OTLP日志导出器]
G --> J[OTLP指标导出器]
H --> K[收集器]
I --> K
J --> K
K --> L[后端分析系统]
style B fill:#f9f,stroke:#333
style E fill:#bbf,stroke:#333
style F fill:#bbf,stroke:#333
style G fill:#bbf,stroke:#333
```

**图示来源**
- [config.go](file://utility/otel/config.go#L1-L67)
- [manager.go](file://utility/otel/manager.go#L1-L257)
- [utils.go](file://utility/otel/utils.go#L1-L230)

**本节来源**
- [config.go](file://utility/otel/config.go#L1-L67)
- [manager.go](file://utility/otel/manager.go#L1-L257)

## 监控功能实现

```mermaid
classDiagram
class Config {
+string ServiceName
+string CollectorURL
+bool Insecure
+string Compressor
+map[string]string Headers
+time.Duration Timeout
+float64 SampleRate
+bool Enable
+[]attribute.KeyValue ResourceAttrs
+Validate() error
+Clone() *Config
}
class Manager {
-Config config
-resource.Resource resource
-trace.TracerProvider tracerProvider
-log.LoggerProvider logProvider
-[]func(context.Context) error shutdownFuncs
+initTracing() error
+initLogging() error
+initMetrics() error
+Shutdown(ctx context.Context) error
+GetConfig() *Config
+GetResource() *resource.Resource
+IsTracingEnabled() bool
+IsLoggingEnabled() bool
+GetTracerProvider() *trace.TracerProvider
+GetLogProvider() *log.LoggerProvider
+CreateTracer(name string) oteltrace.Tracer
+CreateLogger(name string) otellog.Logger
}
class EnhancedLogHandler {
-Manager manager
-bool includeStack
-bool includeContext
-func(*glog.HandlerInput) []otellog.KeyValue customAttrs
+WithIncludeStack(include bool) *EnhancedLogHandler
+WithIncludeContext(include bool) *EnhancedLogHandler
+WithCustomAttributes(fn func(*glog.HandlerInput) []otellog.KeyValue) *EnhancedLogHandler
+Handle(ctx context.Context, in *glog.HandlerInput)
}
Config <|-- Manager : "包含"
Manager --> EnhancedLogHandler : "使用"
note right of Manager
OTel管理器负责初始化和管理
追踪、日志和指标组件
end
```

**图示来源**
- [config.go](file://utility/otel/config.go#L1-L67)
- [manager.go](file://utility/otel/manager.go#L1-L257)
- [handler.go](file://utility/otel/handler.go#L1-L164)

**本节来源**
- [config.go](file://utility/otel/config.go#L1-L67)
- [manager.go](file://utility/otel/manager.go#L1-L257)

## 日志系统配置

```mermaid
flowchart TD
A[日志记录] --> B{OTel是否启用?}
B --> |是| C[创建OTel日志记录]
B --> |否| D[继续默认处理]
C --> E[设置时间戳和严重级别]
E --> F[添加基本属性]
F --> G[添加调用者信息]
G --> H[添加前缀信息]
H --> I{错误级别?}
I --> |是| J[添加堆栈信息]
I --> |否| K[跳过堆栈]
J --> L[添加上下文信息]
K --> L
L --> M[发送到OTel日志提供者]
M --> N[继续下一个处理器]
```

**图示来源**
- [handler.go](file://utility/otel/handler.go#L1-L164)
- [utils.go](file://utility/otel/utils.go#L1-L230)

**本节来源**
- [handler.go](file://utility/otel/handler.go#L1-L164)

## 健康检查机制

```mermaid
sequenceDiagram
participant Client as 客户端
participant Server as HTTP服务器
participant Monitor as 监控控制器
participant API as 监控API
Client->>Server : GET /api/monitor/heathcheck
Server->>Monitor : 调用HealthCheck方法
Monitor->>API : 创建HealthCheckRes响应
API-->>Monitor : 返回响应对象
Monitor-->>Server : 返回OK=true
Server-->>Client : 返回JSON响应 {ok : true}
Note over Client,Server : 健康检查接口用于<br/>验证服务是否正常运行
```

**图示来源**
- [monitor.go](file://api/monitor/monitor.go#L1-L15)
- [heathcheck.go](file://api/monitor/v1/heathcheck.go#L1-L13)
- [monitor_new.go](file://internal/controller/monitor/monitor_new.go#L1-L15)
- [monitor_v1_health_check.go](file://internal/controller/monitor/monitor_v1_health_check.go#L1-L13)

**本节来源**
- [monitor.go](file://api/monitor/monitor.go#L1-L15)
- [heathcheck.go](file://api/monitor/v1/heathcheck.go#L1-L13)

## 命令行监控选项

```mermaid
flowchart TD
A[启动主命令] --> B[初始化HTTP服务器]
B --> C[绑定API路由]
C --> D[注册中间件]
D --> E[注册监控任务]
E --> F[注册轮询任务]
F --> G[启动服务器]
G --> H[监听系统信号]
H --> I{收到SIGINT/SIGTERM?}
I --> |是| J[优雅关闭]
I --> |否| K[继续运行]
J --> L[停止定时任务]
L --> M[关闭线程池]
M --> N[退出程序]
```

**图示来源**
- [cmd.go](file://internal/cmd/cmd.go#L1-L92)
- [monitor.go](file://utility/monitor/monitor.go#L1-L14)

**本节来源**
- [cmd.go](file://internal/cmd/cmd.go#L1-L92)

## 关键性能指标(KPI)

| 指标类别 | 指标名称 | 说明 | 采集方式 |
|---------|--------|------|---------|
| **系统健康** | 服务可用性 | 服务是否正常响应 | 健康检查接口 |
| | CPU使用率 | CPU资源消耗情况 | 系统监控工具 |
| | 内存使用量 | 内存资源消耗情况 | 系统监控工具 |
| | 线程池状态 | 线程池工作状态 | 内置监控接口 |
| **请求性能** | 请求延迟 | API响应时间 | OpenTelemetry追踪 |
| | 错误率 | 失败请求占比 | 日志分析 |
| | 吞吐量 | 每秒处理请求数 | 请求计数器 |
| **业务指标** | 订单处理量 | 订单处理数量 | 业务逻辑计数 |
| | 支付成功率 | 支付成功比例 | 业务状态统计 |
| | 接口调用频率 | 各接口调用次数 | 请求日志分析 |

**本节来源**
- [manager.go](file://utility/otel/manager.go#L1-L257)
- [utils.go](file://utility/otel/utils.go#L1-L230)

## 监控数据可视化与告警

```mermaid
graph TD
A[应用日志] --> B[OpenTelemetry收集器]
C[追踪数据] --> B
D[指标数据] --> B
B --> E[数据处理]
E --> F[存储到时序数据库]
E --> G[存储到日志系统]
E --> H[存储到追踪系统]
F --> I[可视化仪表板]
G --> I
H --> I
I --> J[设置告警规则]
J --> K{触发条件?}
K --> |是| L[发送告警通知]
K --> |否| M[继续监控]
L --> N[邮件/短信/IM通知]
```

**本节来源**
- [config.go](file://utility/otel/config.go#L1-L67)
- [manager.go](file://utility/otel/manager.go#L1-L257)

## 性能监控最佳实践

```mermaid
flowchart TD
A[性能监控目标] --> B[减少请求延迟]
A --> C[降低错误率]
A --> D[优化资源使用]
A --> E[提高系统可用性]
B --> F[使用分布式追踪]
F --> G[识别性能瓶颈]
G --> H[优化慢查询]
H --> I[缓存热点数据]
C --> J[全面的日志记录]
J --> K[错误分类统计]
K --> L[根因分析]
L --> M[修复根本问题]
D --> N[监控资源使用]
N --> O[设置资源限制]
O --> P[优化内存管理]
P --> Q[调整线程池]
E --> R[健康检查机制]
R --> S[自动故障转移]
S --> T[快速恢复]
T --> U[减少停机时间]
```

**本节来源**
- [utils.go](file://utility/otel/utils.go#L1-L230)
- [manager.go](file://utility/otel/manager.go#L1-L257)

## 运维诊断指南

```mermaid
flowchart TD
A[问题诊断流程] --> B{服务是否可用?}
B --> |否| C[检查健康检查接口]
B --> |是| D{响应是否缓慢?}
C --> E[检查进程状态]
C --> F[检查端口占用]
C --> G[检查依赖服务]
D --> |是| H[查看分布式追踪]
D --> |否| I{是否有错误?}
H --> J[定位慢操作]
H --> K[分析调用链]
I --> |是| L[查询错误日志]
I --> |否| M[正常运行]
L --> N[按错误类型分类]
N --> O[查找错误模式]
O --> P[确定根本原因]
P --> Q[实施修复方案]
```

**本节来源**
- [monitor.go](file://api/monitor/monitor.go#L1-L15)
- [heathcheck.go](file://api/monitor/v1/heathcheck.go#L1-L13)
- [utils.go](file://utility/otel/utils.go#L1-L230)