284 lines
9.6 KiB
Markdown
284 lines
9.6 KiB
Markdown
# 日志分析
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
|
||
- [chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs)
|
||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs)
|
||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||
- [main.rs](file://crates/rcoder/src/main.rs)
|
||
- [manager.rs](file://crates/docker_manager/src/manager.rs)
|
||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [日志结构与关键日志点](#日志结构与关键日志点)
|
||
2. [Tracing与OpenTelemetry集成](#tracing与opentelemetry集成)
|
||
3. [关键操作日志记录模式](#关键操作日志记录模式)
|
||
4. [性能瓶颈与错误识别](#性能瓶颈与错误识别)
|
||
5. [日志级别配置与过滤](#日志级别配置与过滤)
|
||
6. [Docker容器日志集成](#docker容器日志集成)
|
||
7. [端到端问题定位](#端到端问题定位)
|
||
|
||
## 日志结构与关键日志点
|
||
|
||
RCoder系统采用结构化日志记录，结合`tracing`和`OpenTelemetry`实现分布式追踪。日志系统在`main.rs`中初始化，配置了文件和控制台双输出。文件日志采用JSON格式，便于后续分析和监控系统集成。
|
||
|
||
日志文件按天滚动保存，保留最近5天的日志文件，文件名前缀分别为`agent-runner`和`rcoder`，分别对应不同的服务组件。日志目录自动创建于项目根目录下的`logs`文件夹中。
|
||
|
||
关键日志点包括：
|
||
- HTTP请求的开始和结束
|
||
- 容器创建、启动和停止
|
||
- 代理服务的状态转换
|
||
- 会话管理操作
|
||
- 错误和异常处理
|
||
|
||
**Section sources**
|
||
- [main.rs](file://crates/agent_runner/src/main.rs#L182-L231)
|
||
- [main.rs](file://crates/rcoder/src/main.rs#L275-L320)
|
||
|
||
## Tracing与OpenTelemetry集成
|
||
|
||
系统通过`tracing_middleware.rs`实现了HTTP请求追踪中间件，为每个请求生成唯一的`trace_id`，并创建相应的span用于日志跟踪。中间件自动从请求头中提取`trace_id`，支持`x-trace-id`、`x-request-id`、`traceparent`等常见追踪头。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client as "客户端"
|
||
participant Rcoder as "RCoder服务"
|
||
participant Agent as "AgentRunner服务"
|
||
Client->>Rcoder : POST /chat (带trace_id)
|
||
Rcoder->>Rcoder : 生成/提取trace_id
|
||
Rcoder->>Rcoder : 记录请求开始
|
||
Rcoder->>Agent : 转发请求 (传递trace_id)
|
||
Agent->>Agent : 记录代理处理
|
||
Agent-->>Rcoder : 返回响应
|
||
Rcoder->>Rcoder : 记录请求完成
|
||
Rcoder-->>Client : 返回响应
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L179)
|
||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L1-L179)
|
||
|
||
**Section sources**
|
||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L179)
|
||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L1-L179)
|
||
|
||
## 关键操作日志记录模式
|
||
|
||
### HTTP入口日志记录
|
||
|
||
在`chat_handler.rs`中，HTTP请求的处理过程有详细的日志记录。当处理聊天请求时，系统会记录请求的开始、项目ID的生成、会话状态的检查等关键信息。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start([开始处理聊天请求]) --> Validate["验证请求参数"]
|
||
Validate --> CheckStatus["检查Agent状态"]
|
||
CheckStatus --> RemoveSession["移除旧会话"]
|
||
RemoveSession --> CreateWorkspace["创建项目工作目录"]
|
||
CreateWorkspace --> SelectAgent["选择Agent类型"]
|
||
SelectAgent --> SendTask["发送本地任务"]
|
||
SendTask --> AwaitResponse["等待代理响应"]
|
||
AwaitResponse --> HandleResult["处理响应结果"]
|
||
HandleResult --> End([返回响应])
|
||
style Start fill:#4CAF50,stroke:#388E3C
|
||
style End fill:#4CAF50,stroke:#388E3C
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L320)
|
||
|
||
**Section sources**
|
||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L320)
|
||
|
||
### 代理服务日志记录
|
||
|
||
在`agent_service.rs`中，代理服务的启动和管理有明确的日志记录。系统通过`AcpAgentService` trait定义了统一的接口，不同类型的代理（如Claude、Codex）实现该接口。
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class AcpAgentService {
|
||
<<trait>>
|
||
+start_agent_service(chat_prompt, model_provider) Result~AcpConnectionInfo~
|
||
+agent_type_name() &'static str
|
||
}
|
||
class AgentType {
|
||
+Claude
|
||
+Codex
|
||
}
|
||
AcpAgentService <|-- AgentType : "实现"
|
||
AgentType --> "ClaudeCodeAgent" : "调用"
|
||
AgentType --> "CodexAgent" : "调用"
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L7-L62)
|
||
|
||
**Section sources**
|
||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L7-L62)
|
||
|
||
## 性能瓶颈与错误识别
|
||
|
||
### 性能瓶颈识别
|
||
|
||
通过分析日志中的时间戳和处理时长，可以识别系统性能瓶颈。关键的性能指标包括：
|
||
|
||
- HTTP请求处理时间
|
||
- 容器创建和启动时间
|
||
- 代理服务响应时间
|
||
- 网络通信延迟
|
||
|
||
日志中的emoji标记有助于快速识别不同类型的日志：
|
||
- 🚀 表示开始处理
|
||
- ✅ 表示成功完成
|
||
- ❌ 表示错误或失败
|
||
- ⚠️ 表示警告或需要注意的情况
|
||
|
||
### 错误堆栈分析
|
||
|
||
系统在关键错误点记录详细的错误信息，包括错误代码、消息和堆栈跟踪。例如，在`chat_handler.rs`中，当代理处理失败时，系统会记录错误详情：
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[收到代理执行结果] --> B{结果是否成功?}
|
||
B --> |是| C[检查响应错误]
|
||
C --> D{有错误?}
|
||
D --> |是| E[记录错误日志]
|
||
D --> |否| F[记录成功日志]
|
||
B --> |否| G[记录接收失败日志]
|
||
style E fill:#f44336,stroke:#d32f2f
|
||
style G fill:#f44336,stroke:#d32f2f
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L289-L318)
|
||
|
||
**Section sources**
|
||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L289-L318)
|
||
|
||
## 日志级别配置与过滤
|
||
|
||
### 日志级别配置
|
||
|
||
系统通过`tracing_subscriber::EnvFilter`配置日志级别，支持环境变量配置。默认配置如下：
|
||
|
||
- `rcoder=debug`：RCoder组件的调试级别
|
||
- `tower_http=debug`：HTTP中间件的调试级别
|
||
- `axum_tracing_opentelemetry=info`：OpenTelemetry追踪的普通级别
|
||
|
||
### 日志过滤技巧
|
||
|
||
可以通过环境变量`RUST_LOG`来动态调整日志级别，例如：
|
||
|
||
```bash
|
||
# 只显示错误日志
|
||
export RUST_LOG=error
|
||
|
||
# 显示RCoder组件的调试日志
|
||
export RUST_LOG=rcoder=debug
|
||
|
||
# 显示所有组件的详细日志
|
||
export RUST_LOG=debug
|
||
```
|
||
|
||
**Section sources**
|
||
- [main.rs](file://crates/agent_runner/src/main.rs#L219-L221)
|
||
- [main.rs](file://crates/rcoder/src/main.rs#L310-L311)
|
||
|
||
## Docker容器日志集成
|
||
|
||
### 容器管理日志
|
||
|
||
`docker_manager`模块提供了完整的容器管理功能，包括创建、启动、停止和清理容器。每个操作都有相应的日志记录：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Rcoder as "RCoder服务"
|
||
participant Docker as "Docker守护进程"
|
||
Rcoder->>Docker : 创建容器
|
||
Docker-->>Rcoder : 返回容器ID
|
||
Rcoder->>Rcoder : 记录容器创建
|
||
Rcoder->>Docker : 启动容器
|
||
Docker-->>Rcoder : 启动成功
|
||
Rcoder->>Rcoder : 记录容器启动
|
||
Rcoder->>Docker : 检查容器健康
|
||
Docker-->>Rcoder : 健康状态
|
||
Rcoder->>Rcoder : 记录健康检查
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L81-L352)
|
||
|
||
**Section sources**
|
||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L81-L352)
|
||
|
||
### 容器日志获取
|
||
|
||
系统提供了获取容器日志的功能，可以通过`get_container_logs`方法获取指定容器的日志：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[获取容器日志] --> B{容器是否存在?}
|
||
B --> |是| C[调用Docker API]
|
||
C --> D[获取日志流]
|
||
D --> E[合并日志内容]
|
||
E --> F[返回日志字符串]
|
||
B --> |否| G[返回错误]
|
||
style G fill:#f44336,stroke:#d32f2f
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L588-L623)
|
||
|
||
**Section sources**
|
||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L588-L623)
|
||
|
||
## 端到端问题定位
|
||
|
||
### 请求生命周期追踪
|
||
|
||
通过`trace_id`可以追踪请求从HTTP入口到代理执行的完整生命周期。系统在`chat_handler.rs`中实现了请求转发，保持了`trace_id`的传递：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client as "客户端"
|
||
participant Rcoder as "RCoder服务"
|
||
participant Container as "Agent容器"
|
||
Client->>Rcoder : 发送请求 (带trace_id)
|
||
Rcoder->>Rcoder : 记录请求开始
|
||
Rcoder->>Container : 转发请求 (传递trace_id)
|
||
Container->>Container : 处理请求
|
||
Container-->>Rcoder : 返回响应
|
||
Rcoder->>Rcoder : 记录请求完成
|
||
Rcoder-->>Client : 返回响应
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L110-L320)
|
||
|
||
**Section sources**
|
||
- [chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L110-L320)
|
||
|
||
### 状态转换异常检测
|
||
|
||
系统通过日志记录关键状态的转换，可以检测异常状态。例如，在容器管理中，系统会检查容器的健康状态：
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> Idle
|
||
Idle --> Creating : "创建容器"
|
||
Creating --> Running : "启动成功"
|
||
Creating --> Error : "启动失败"
|
||
Running --> Stopped : "停止容器"
|
||
Running --> Error : "健康检查失败"
|
||
Stopped --> Idle : "清理完成"
|
||
Error --> Idle : "错误处理"
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L758-L800)
|
||
|
||
**Section sources**
|
||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L758-L800) |