Agent Session Monitor - Quick Start

实时Agent对话观测程序，用于监控Higress访问日志，追踪多轮对话的token开销和模型使用情况。

快速开始

1. 运行Demo

cd example
bash demo.sh

这将：

解析示例日志文件
列出所有session
显示session详细信息（包括完整的messages、question、answer、reasoning、tool_calls）
按模型和日期统计token开销
导出FinOps报表

2. 启动Web界面（推荐）

# 先解析日志生成session数据
python3 main.py --log-path /var/log/higress/access.log --output-dir ./sessions

# 启动Web服务器
python3 scripts/webserver.py --data-dir ./sessions --port 8888

# 浏览器访问
open http://localhost:8888

Web界面功能：

📊 总览所有session，按模型分组统计
🔍 点击session ID下钻查看完整对话
💬 查看每轮的messages、question、answer、reasoning、tool_calls
💰 实时计算token开销和成本
🔄 每30秒自动刷新

3. 在Clawdbot对话中使用

当用户询问当前会话token消耗时，生成观测链接：

你的当前会话ID: agent:main:discord:channel:1465367993012981988

查看详情：http://localhost:8888/session?id=agent:main:discord:channel:1465367993012981988

点击可以看到：
✅ 完整对话历史（每轮messages）
✅ Token消耗明细
✅ 工具调用记录
✅ 成本统计

4. 使用CLI查询（可选）

# 查看session详细信息
python3 scripts/cli.py show <session-id>

# 列出所有session
python3 scripts/cli.py list

# 按模型统计
python3 scripts/cli.py stats-model

# 导出报表
python3 scripts/cli.py export finops-report.json

核心功能

✅ 完整对话追踪：记录每轮对话的完整messages、question、answer、reasoning、tool_calls
✅ Token开销统计：区分input/output/reasoning/cached token，实时计算成本
✅ Session聚合：按session_id关联多轮对话
✅ Web可视化界面：浏览器访问，总览+下钻查看session详情
✅ 实时URL生成：Clawdbot可根据当前会话ID生成观测链接
✅ FinOps报表：导出JSON/CSV格式的成本分析报告

日志格式要求

Higress访问日志需要包含ai_log字段（JSON格式），示例：

{
  "__file_offset__": "1000",
  "timestamp": "2026-02-01T09:30:15Z",
  "ai_log": "{\"session_id\":\"sess_abc\",\"messages\":[...],\"question\":\"...\",\"answer\":\"...\",\"input_token\":250,\"output_token\":160,\"model\":\"Qwen3-rerank\"}"
}

ai_log字段支持的属性：

session_id: 会话标识（必需）
messages: 完整对话历史
question: 当前轮次问题
answer: AI回答
reasoning: 思考过程（DeepSeek等模型）
tool_calls: 工具调用列表
input_token: 输入token数
output_token: 输出token数
model: 模型名称
response_type: 响应类型

输出目录结构

sessions/
├── agent:main:discord:1465367993012981988.json
└── agent:test:discord:9999999999999999999.json

每个session文件包含：

基本信息（创建时间、更新时间、模型）
Token统计（总输入、总输出、总reasoning、总cached）
对话轮次列表（每轮的完整messages、question、answer、reasoning、tool_calls）

常见问题

Q: 如何在Higress中配置session_id header？
A: 在ai-statistics插件中配置session_id_header，或使用默认header（x-openclaw-session-key、x-clawdbot-session-key等）。详见PR #3420。

Q: 支持哪些模型的pricing？
A: 目前支持Qwen、DeepSeek、GPT-4、Claude等主流模型。可以在main.py的TOKEN_PRICING字典中添加新模型。

Q: 如何实时监控日志文件变化？
A: 直接运行main.py即可，程序使用定时轮询机制（每秒自动检查一次），无需安装额外依赖。

Q: CLI查询速度慢？
A: 大量session时，可以使用--limit限制结果数量，或按条件过滤（如--sort-by cost只查看成本最高的session）。

下一步

集成到Higress FinOps Dashboard
支持更多模型的pricing
添加趋势预测和异常检测
支持多数据源聚合分析

4.1 KiB Raw Permalink Blame History Unescape Escape