---
sidebar_position: 11
title: 日志管理
description: ZHub 日志配置、格式分析、故障排查和监控指南
keywords: [ZHub日志, 日志管理, 日志分析, 故障排查, 监控]
---

# 日志管理

ZHub 日志文件配置、分析和故障排查指南。

## 目录

- [日志配置](#日志配置)
- [日志文件位置](#日志文件位置)
- [服务端日志](#日志内容分析)
- [Java客户端日志](#java-客户端日志)
- [日志分析](#日志分析)
- [日志轮转](#日志轮转)
- [故障排查](#故障排查)

## 日志配置

### 基础配置

**app.ini 配置**：
```ini
[log]
level=info          # 日志级别: debug, info, error
handlers=console    # 日志处理器: console, file
file=zhub.log       # 日志文件名
```

### 日志级别说明

| 级别 | 说明 | 使用场景 |
|------|------|----------|
| debug | 调试信息 | 开发调试，包含详细的执行流程 |
| info | 一般信息 | 生产环境，记录重要操作 |
| error | 错误信息 | 严重错误，需要关注 |

## 日志文件位置

### 默认位置
```bash
# 当前目录下的日志文件
./zhub.log
```

### 自定义位置
```ini
# app.ini 中指定日志目录
[log]
file=/var/log/zhub/zhub.log
```

## 日志内容分析

### 连接接入日志

**连接建立**：
```
2024/01/15 10:30:15.123456 zbus.go:291: [Info] conn start: 127.0.0.1:12345 [1]
```
- 格式：`[Info] conn start: IP:端口 [连接序号]`
- 连接序号：每个新连接递增的数字标识

**连接断开**：
```
2024/01/15 10:30:20.123456 zbus.go:302: [Info] conn closed: 127.0.0.1:12345 [ 1 ]
```
- 格式：`[Info] conn closed: IP:端口 [ 连接序号 ]`
- 包含正常断开和异常断开

**认证过程**：
```
2024/01/15 10:30:15.123456 zbus-message-handler.go:84: [Info] [1] -Auth: publish [user-login]
2024/01/15 10:30:15.123456 zbus-message-handler.go:122: [Info] [1] cmd: publish, auth [OK]
```
- `-Auth:` 表示权限不足
- `auth [OK]` 表示认证成功

### 消息收发日志

**消息发布**：
```
2024/01/15 10:30:15.123456 zbus-message-handler.go:45: [1] cmd: publish user-login {"userId":"12345"}
```
- 格式：`[连接序号] cmd: publish 主题名 消息内容`（debug级别）
- 仅在debug级别下显示

**消息订阅**：
```
2024/01/15 10:30:15.123456 zbus-message-handler.go:45: [1] cmd: subscribe user-login order-create
2024/01/15 10:30:15.123456 zbus-message-handler.go:122: [Info] [1] cmd: subscribe, auth [OK]
```
- 格式：`[连接序号] cmd: subscribe 主题列表`（debug级别）
- 支持多主题订阅，空格分隔

**广播消息**：
```
2024/01/15 10:30:15.123456 zbus-message-handler.go:45: [1] cmd: broadcast topic-abc hello!
```
- 格式：`[连接序号] cmd: broadcast 主题名 消息内容`（debug级别）

**延时消息**：
```
2024/01/15 10:30:15.123456 zbus-message-handler.go:45: [1] cmd: delay order-timeout 30s 订单超时
```
- 格式：`[连接序号] cmd: delay 主题名 延时时间 消息内容`（debug级别）

### RPC 调用日志

**RPC 调用**：
```
2024/01/15 10:30:15.123456 zbus-message-handler.go:45: [1] cmd: rpc user-get-info {"ruk":"app1::12345"}
```
- 格式：`[连接序号] cmd: rpc 服务名 RPC参数`（debug级别）
- RPC参数包含ruk（回复标识）

**RPC 服务离线**：
```
2024/01/15 10:30:15.123456 zbus-message-handler.go:132: [1] : rpc user-get-info no subscribe
```
- 格式：`[连接序号] : rpc 服务名 no subscribe`
- 表示没有客户端订阅该RPC服务

**RPC 权限不足**：
```
2024/01/15 10:30:15.123456 zbus-message-handler.go:84: [Info] [1] -Auth: rpc [user-get-info]
```
- 格式：`[Info] [连接序号] -Auth: rpc [服务名]`

### 定时任务日志

**定时任务执行**：
```
2024/01/15 10:30:00.123456 monitor.go:56: [Info] broadcast timer T:A 执行
2024/01/15 10:30:05.123456 monitor.go:56: [Info] broadcast timer T:B 执行
```
- 格式：`[Info] broadcast timer 任务名 执行`
- 来自monitor模块的定时任务执行日志

**定时任务订阅**：
```
2024/01/15 10:30:15.123456 zbus-message-handler.go:45: [1] cmd: timer T:A T:B
```
- 格式：`[连接序号] cmd: timer 任务列表`（debug级别）
- 客户端订阅定时任务时记录

## Java 客户端日志

### 消息接收日志

**订阅消息**：
```
FINEST: topic[user.login]: {"userId":"12345","username":"张三"}
```
- 格式：`FINEST: topic[主题名]: 消息内容`
- 记录接收到的订阅消息

**广播消息**：
```
FINEST: topic[topic-abc]: hello!
```
- 格式：`FINEST: topic[主题名]: 消息内容`

### 定时任务日志

**任务触发**：
```
FINEST: timer[T:A]: 
```
- 格式：`FINEST: timer[任务名]: `

**任务执行完成**：
```
FINEST: timer [T:A] : elapsed time 15 ms
```
- 格式：`FINEST: timer [任务名] : elapsed time 耗时 ms`

### RPC 调用日志

**RPC响应**：
```
FINEST: rpc-back:[user.getInfo]: {"retcode":0,"result":"用户信息"}
```
- 格式：`FINEST: rpc-back:[服务名]: 响应内容`

**RPC错误**：
```
WARNING: rpc-back[user.getInfo] event accept error :{"retcode":500,"result":"服务错误"}
```
- 格式：`WARNING: rpc-back[服务名] event accept error :响应内容`

### 错误日志

**超时错误**：
```
SEVERE: timer [T:A] time out: 5 S
```
- 格式：`SEVERE: timer [任务名] time out: 超时时间 S`

**处理异常**：
```
WARNING: topic[user.login] event accept error :{"userId":"12345"}
SEVERE: topic[user.login] event deal time out: 5 S, value: {"userId":"12345"}
```
- 格式：`WARNING: topic[主题名] event accept error :消息内容`
- 格式：`SEVERE: topic[主题名] event deal time out: 超时时间 S, value: 消息内容`

## 日志分析

### 关键日志识别

**连接状态监控**：
- `conn start:` - 新连接建立
- `conn closed:` - 连接断开
- `-Auth:` - 权限认证失败

**消息处理监控**：
- `cmd: publish` - 消息发布（debug级别）
- `cmd: subscribe` - 消息订阅
- `cmd: rpc` - RPC调用
- `no subscribe` - 服务离线

**Java客户端监控**：
- `topic[主题名]:` - 消息接收
- `timer[任务名]:` - 定时任务触发
- `rpc-back:[服务名]:` - RPC响应
- `time out:` - 超时错误
- `event accept error` - 处理异常
- `event deal time out` - 处理超时

**错误信息识别**：
- `-Error:` - 系统错误
- `Recovered:` - 异常恢复
- `-Auth:` - 权限不足

### 监控要点

1. **连接稳定性**：关注连接建立和断开的频率
2. **权限问题**：监控`-Auth:`日志，排查权限配置
3. **服务可用性**：关注`no subscribe`日志，确保RPC服务正常
4. **系统健康**：检查`-Error:`和`Recovered:`日志
5. **客户端性能**：监控`time out:`日志，关注处理超时
6. **消息处理**：观察`topic[主题名]:`日志，确保消息正常接收

## 日志轮转

### 手动轮转
```bash
# 重命名当前日志文件
mv zhub.log zhub.log.$(date +%Y%m%d)

# 重启服务
./zhub.sh restart
```

## 故障排查

### 常见问题

**1. 日志文件过大**
- 定期清理旧日志文件
- 调整日志级别为info

**2. 日志级别过高**
- 生产环境建议使用info级别
- 开发环境可使用debug级别

### 最佳实践

1. **定期检查**：关注错误和权限相关日志
2. **监控连接**：观察连接建立和断开情况
3. **服务状态**：确保RPC服务正常运行
4. **日志轮转**：定期清理旧日志文件
5. **级别设置**：生产环境使用info级别