Claude Code Router日志系统：实时监控与故障排查指南

Claude Code Router日志系统：实时监控与故障排查指南

【免费下载链接】claude-code-router Use Claude Code without an Anthropics account and route it to another LLM provider 项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router

🎯 痛点直击：为什么需要专业的日志监控？

还在为Claude Code Router的API调用失败、模型路由异常、性能瓶颈而头疼吗？每次遇到问题都要手动翻找日志文件，却不知道从何下手？本文将为你提供一套完整的日志监控与故障排查解决方案，让你能够：

• ✅ 实时监控API调用状态和性能指标
• ✅ 快速定位路由决策和模型切换问题
• ✅ 自动化日志分析和异常告警
• ✅ 深度排查身份验证和配置错误
• ✅ 优化系统性能和资源利用率

📊 日志系统架构解析

Claude Code Router采用双层级日志架构，确保系统运行状态的全方位监控：

核心配置文件解析

日志系统的配置主要在 ~/.claude-code-router/config.json 中：

{
  "LOG": true,
  "LOG_LEVEL": "debug",
  "APIKEY": "your-secret-key",
  "HOST": "127.0.0.1",
  "NON_INTERACTIVE_MODE": false,
  "API_TIMEOUT_MS": 600000
}

配置参数详解：

参数	类型	默认值	说明
LOG	boolean	true	启用/禁用日志系统
LOG_LEVEL	string	"debug"	日志级别：fatal, error, warn, info, debug, trace
APIKEY	string	-	API密钥，用于身份验证
HOST	string	"127.0.0.1"	服务器监听地址
NON_INTERACTIVE_MODE	boolean	false	非交互模式（CI/CD环境）
API_TIMEOUT_MS	number	600000	API调用超时时间（10分钟）

🔍 日志级别与内容详解

日志级别优先级表

级别	颜色	说明	使用场景
fatal	🔴	致命错误	系统无法继续运行
error	❌	错误事件	API调用失败、路由错误
warn	⚠️	警告事件	配置问题、性能警告
info	ℹ️	信息事件	正常操作记录
debug	🐛	调试信息	详细运行信息
trace	📍	跟踪信息	最详细的调试信息

典型日志格式示例

服务器级日志（Pino格式）：

{
  "level": 30,
  "time": 1735736218000,
  "pid": 12345,
  "hostname": "localhost",
  "msg": "API call completed",
  "provider": "deepseek",
  "model": "deepseek-chat",
  "status": 200,
  "duration": 1250,
  "tokens": 256
}

应用级日志（自定义格式）：

[2025-09-01T15:30:18.123Z] Router selected model: deepseek,deepseek-chat for session: session-abc123
[2025-09-01T15:30:19.456Z] Transformer applied: deepseek to request
[2025-09-01T15:30:20.789Z] API call to DeepSeek completed in 1250ms with 200 status

🚀 实时监控实战指南

1. 实时日志跟踪命令

# 实时跟踪服务器日志
tail -f ~/.claude-code-router/logs/ccr-*.log | jq '.'

# 实时跟踪应用日志
tail -f ~/.claude-code-router/claude-code-router.log

# 过滤特定级别的日志
tail -f ~/.claude-code-router/logs/ccr-*.log | jq 'select(.level >= 40)'

# 监控特定模型的API调用
tail -f ~/.claude-code-router/logs/ccr-*.log | jq 'select(.model == "deepseek-chat")'

2. 自动化监控脚本

创建监控脚本 monitor_ccr.sh：

#!/bin/bash

LOG_DIR="$HOME/.claude-code-router"
ALERT_EMAIL="your-email@example.com"

# 监控错误日志
monitor_errors() {
    tail -n 100 -f "$LOG_DIR/logs/"ccr-*.log | \
    while read line; do
        if echo "$line" | jq -e '.level >= 40' > /dev/null 2>&1; then
            echo "❌ ERROR DETECTED: $line"
            # 发送告警邮件
            echo "Claude Code Router Error: $line" | mail -s "CCR Error Alert" "$ALERT_EMAIL"
        fi
    done
}

# 监控性能指标
monitor_performance() {
    tail -n 100 -f "$LOG_DIR/logs/"ccr-*.log | \
    while read line; do
        duration=$(echo "$line" | jq -r '.duration // 0')
        if (( duration > 5000 )); then
            echo "⚠️  SLOW API CALL: ${duration}ms - $line"
        fi
    done
}

# 启动监控
monitor_errors &
monitor_performance &

3. 日志分析仪表板

使用 jq 和 awk 创建实时分析：

# 实时API成功率统计
tail -f ~/.claude-code-router/logs/ccr-*.log | \
jq -r 'select(.status != null) | "\(.status)"' | \
awk '
{
    total++
    if ($1 >= 200 && $1 < 300) success++
    else if ($1 >= 400 && $1 < 500) client_errors++
    else if ($1 >= 500) server_errors++
    
    if (total % 10 == 0) {
        printf "\r✅ Success: %.1f%% | ❌ Client Errors: %.1f%% | 🔴 Server Errors: %.1f%% | 📊 Total: %d", 
            (success/total)*100, (client_errors/total)*100, (server_errors/total)*100, total
    }
}'

🛠️ 故障排查手册

常见问题排查表

问题现象	可能原因	排查命令	解决方案
API调用失败	网络问题、API密钥错误	grep "status.*5[0-9][0-9]"	检查网络连接和API密钥配置
路由决策错误	配置错误、模型不可用	grep "Router selected"	验证路由配置和模型可用性
性能下降	网络延迟、模型负载高	jq 'select(.duration > 5000)'	优化网络或切换模型
身份验证失败	APIKEY配置错误	grep "401\|403"	检查config.json中的APIKEY配置
内存泄漏	日志文件过大	du -sh ~/.claude-code-router/logs/	配置日志轮转和清理

详细排查流程

1. API调用问题排查

# 查找最近的API错误
grep -A5 -B5 "error\|failed\|status.*[45][0-9][0-9]" \
~/.claude-code-router/claude-code-router.log

# 分析错误类型分布
jq -r '.level' ~/.claude-code-router/logs/ccr-*.log | \
sort | uniq -c | sort -nr

# 查看具体的错误详情
jq 'select(.level >= 40) | {time: .time, msg: .msg, provider: .provider, model: .model}' \
~/.claude-code-router/logs/ccr-*.log

2. 路由决策分析

# 查看路由决策记录
grep "Router selected" ~/.claude-code-router/claude-code-router.log

# 分析模型使用频率
grep "Router selected" ~/.claude-code-router/claude-code-router.log | \
awk '{print $NF}' | sort | uniq -c | sort -nr

# 检查路由配置是否正确
jq '.Router' ~/.claude-code-router/config.json

3. 性能问题诊断

# 查找慢速API调用
jq 'select(.duration > 3000) | {model: .model, duration: .duration, time: .time}' \
~/.claude-code-router/logs/ccr-*.log

# 计算平均响应时间
jq -r '.duration // 0' ~/.claude-code-router/logs/ccr-*.log | \
awk '{sum+=$1; count++} END {print "平均响应时间:", sum/count, "ms"}'

# 按模型分组统计性能
jq -r 'select(.duration != null) | "\(.model) \(.duration)"' \
~/.claude-code-router/logs/ccr-*.log | \
awk '{sum[$1]+=$2; count[$1]++} END {for (m in sum) print m, sum[m]/count[m], "ms"}'

📈 高级监控与优化

1. Prometheus监控集成

创建 prometheus.yml 配置：

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'claude-code-router'
    static_configs:
      - targets: ['localhost:3456']
    metrics_path: '/metrics'

2. Grafana仪表板配置

使用以下查询创建监控面板：

-- API成功率
100 * (sum(rate(api_calls_total{status=~"2.."}[5m])) / sum(rate(api_calls_total[5m])))

-- 平均响应时间
avg(rate(api_duration_seconds_sum[5m])) / avg(rate(api_duration_seconds_count[5m]))

-- 错误率
sum(rate(api_calls_total{status=~"4..|5.."}[5m])) / sum(rate(api_calls_total[5m]))

3. 自动化告警规则

groups:
- name: claude-code-router
  rules:
  - alert: HighErrorRate
    expr: rate(api_calls_total{status=~"4..|5.."}[5m]) / rate(api_calls_total[5m]) > 0.1
    for: 5m
    labels:
      severity: critical
    annotations:
      summary: "High error rate detected"
      description: "Error rate is above 10% for the last 5 minutes"
  
  - alert: SlowResponse
    expr: avg(rate(api_duration_seconds_sum[5m])) / avg(rate(api_duration_seconds_count[5m])) > 3
    for: 10m
    labels:
      severity: warning
    annotations:
      summary: "Slow API responses"
      description: "Average response time exceeds 3 seconds"

🧹 日志维护与管理

1. 自动化日志清理

Claude Code Router内置日志轮转机制，但你可以进一步优化：

# 手动清理旧日志（保留最近7天）
find ~/.claude-code-router/logs/ -name "ccr-*.log" -mtime +7 -delete

# 设置cron任务自动清理
0 2 * * * find $HOME/.claude-code-router/logs/ -name "ccr-*.log" -mtime +7 -delete

2. 日志压缩归档

# 压缩旧日志节省空间
find ~/.claude-code-router/logs/ -name "ccr-*.log" -mtime +30 -exec gzip {} \;

# 创建月度归档
tar -czf ~/ccr-logs-$(date +%Y-%m).tar.gz ~/.claude-code-router/logs/ccr-*.log

🎯 总结与最佳实践

通过本指南，你应该已经掌握了：

1. 实时监控能力：能够实时跟踪API调用状态和系统性能
2. 故障排查技能：快速定位和解决常见的路由和API问题
3. 自动化运维：设置自动化监控告警和日志维护流程
4. 性能优化：基于日志数据分析进行系统调优

最佳实践清单：

• ✅ 定期检查日志文件大小和轮转配置
• ✅ 设置适当的日志级别（生产环境建议使用 info）
• ✅ 配置自动化监控和告警机制
• ✅ 定期分析性能指标和错误模式
• ✅ 保持日志备份和归档策略

现在你已经具备了专业的Claude Code Router日志监控与故障排查能力，可以确保你的AI应用始终稳定高效运行！

【免费下载链接】claude-code-router Use Claude Code without an Anthropics account and route it to another LLM provider 项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router