# stackwatch

**Repository Path**: AllenMoving/stackwatch

## Basic Information

- **Project Name**: stackwatch
- **Description**: AI-driven root cause analysis for Java production errors (stacktrace fingerprint + LLM RCA + weekly digest)
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://allenmuu.github.io/stackwatch/
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-23
- **Last Updated**: 2026-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# StackWatch

[English](README.md) | **中文**

![Java](https://img.shields.io/badge/Java-21-ED8B00?logo=openjdk&logoColor=white)
![Spring Boot](https://img.shields.io/badge/Spring%20Boot-4.1-6DB33F?logo=springboot&logoColor=white)
![Spring AI](https://img.shields.io/badge/Spring%20AI-2.0-6DB33F)
![License](https://img.shields.io/badge/License-MIT-blue)

> AI 驱动的 Java 生产错误根因分析 - 异常堆栈指纹归并 + LLM 根因定位 + 定时周报聚合。

将生产异常堆栈自动投喂 LLM 进行根因定位与分类归并，结合定时任务按周聚合高频错误并推送飞书周报。

**目标：** 生产故障平均定位耗时缩短约 40%，高频问题发现周期由天级缩短至小时级。

## 目录

- [文档](#文档)
- [架构总览](#架构总览)
  - [分析层三层归并（核心）](#分析层三层归并核心)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [当前状态](#当前状态)
- [近期亮点](#近期亮点)
- [技术栈](#技术栈)
- [开源致谢](#开源致谢)
- [许可证](#许可证)

## 文档

| 文档 | 内容 |
|------|------|
| 📐 [详细设计](docs/detailed-design.md) | 架构详设、模块设计、核心流程、数据结构、表结构、接口、配置 |
| 🧭 [选型分析](docs/tech-selection.md) | 每个技术选型的备选方案、对比维度、决策与理由 |
| 🚀 [升级路径](docs/upgrade-path.md) | 当前状态、后续演进路线（V1.x -> V3.x）、优先级建议 |

## 架构总览

五层主链路 + 两层横切：

```mermaid
flowchart TD
    C[① 采集层 Collector<br/>Logback / HTTP / Kafka] --> P[② 预处理层<br/>指纹去重]
    P --> A[③ 分析层 Analyzer<br/>L1 / L2 / L3 三层级联]
    A --> G[④ 聚合层<br/>激增检测 + 按周聚合]
    G --> N[⑤ 投递层<br/>飞书告警 + 周报]
    A -.-> M[横切A 度量层<br/>耗时 · 准确率 · token 成本]
    A -.-> F[横切B 反馈层<br/>研发反馈飞轮]
```

### 分析层三层归并（核心）

分析层是系统中枢。绝大多数异常在 L1/L2 免费归并，仅约 1% 真正调用 LLM。

| 层级 | 机制 | token 成本 |
|------|------|------------|
| **L1** | 指纹精确命中缓存 | ≈ 0 |
| **L2** | 向量近似归并 | ≈ 0 |
| **L3** | LLM 簇代表根因分析 | 真正调 LLM（约 1%） |

### 复核级别与反馈飞轮

成本阶梯之外，L3 路径还套了一层**三档复核门控**（借鉴 阿里云开发者公众号PagePilot 置信度分档）：

| 置信度 / 信号 | 复核级别 | 动作 |
|--------------|---------|------|
| >= 高阈值（0.9）且有证据 | `AUTO_CONFIRMED` | 自动归因，不打扰研发 |
| 兜底阈值（0.6）与高阈值之间且有证据 | `NEEDS_CONFIRMATION` | 输出根因，标记待确认（低介入确认） |
| < 兜底阈值 / 无证据 / LLM 失败 | `NEEDS_HUMAN_REVIEW` | 转人工排查 |

反馈层是**正负双向飞轮**：研发通过 `POST /feedback` 确认或纠正根因 -> 正样本（few-shot，「该这么答」）+ 当携带 `wrongRootCause` 时负样本（anti-pattern，「别这么答」）。两者都注入下一次 L3 prompt--正样本引导、负样本警示。这是 PagePilot `known-failures` 思想在负样本侧的落地，与 few-shot 正样本侧对偶，构成完整自学习闭环。

### 上下文优化与语义缓存

LLM 前置两道防线，保持 Prompt 精简、压住 token 账单：

- **语义缓存（L2）**。L2 不只是近似归并，本质是语义缓存：新错误 embedding 与已有簇相似度 ≥ 0.92 时，直接返回该簇的根因，零 LLM 调用。命中后结果**反向填充 L1**，后续相同指纹在 L1 直接命中--缓存梯度自洽。这对 RCA 是理想场景：同一根因会以大量字面不同但语义相同的堆栈实例反复出现。
- **上下文优化**。`ContextOptimizer` 在 Prompt 入参（`exceptionMessage`、`mdc`）与每个 `@Tool` 返回值进入 LLM 前做截断。生产异常 message 可能携带完整 SQL / 响应体，`queryTraceContext` 接 SkyWalking/ARMS 后单 trace 日志可达数万字符--没有这道闸，上下文窗口易爆满、幻觉风险上升。阈值走 `stackwatch.context-optimizer.*` 配置。

## 环境要求

- **JDK 21+** - Spring Boot 4.1 + Spring AI 2.0 强制要求（不支持 Java 8/11/17）
- **Maven 3.6+**

## 快速开始

```bash
# 1. 配置 LLM API Key（走环境变量，禁止写入代码）
export DASHSCOPE_API_KEY=sk-...

# 2. 构建
mvn clean package

# 3. 运行
mvn spring-boot:run

# 4. 试用：输入异常堆栈，获取 LLM 根因
curl -X POST http://localhost:8080/analyze \
  -H "Content-Type: application/json" \
  -d '{"appName":"order-service","exceptionType":"NullPointerException","exceptionMessage":"Cannot invoke method on null","stackTrace":["com.foo.OrderService.process(OrderService.java:42)","com.foo.OrderController.handle(OrderController.java:17)"]}'
```

## 当前状态
MVP 阶段 - 五层主链路 + 两层横切均已实现；L2 / Kafka 默认关闭，按配置解锁。

| 层 | 状态 |
|----|------|
| domain 数据结构（不可变 record） | ✅ 已完成 |
| ② 预处理层 - 指纹生成（SHA-256 + 框架帧过滤 + 版本化） | ✅ 已完成 |
| ③ 分析层 - L1 缓存 + L2 向量归并 + L3 LLM 根因（结构化输出 + Function Calling） | ✅ 已完成 |
| 上下文优化 - ContextOptimizer（截断 Prompt 入参与 @Tool 返回值） | ✅ 已完成 |
| ① 采集层 - Logback Appender + HTTP + Kafka（默认关闭，渐进式解锁） | ✅ 已完成 |
| ④ ⑤ 聚合层 / 投递层 - 实时激增检测 + 飞书周报 | ✅ 已完成 |
| 横切 A/B - Micrometer 度量 + 正负双向反馈飞轮（few-shot + anti-pattern） | ✅ 已完成 |

## 近期亮点

- **上下文优化层**（`ContextOptimizer`）- 在 LLM 前截断 Prompt 入参（`exceptionMessage` / `mdc`）与 `@Tool` 返回值，防止接入真实数据源（SkyWalking/ARMS）后上下文窗口爆满。
- **语义缓存** - L2 在 embedding 相似度 ≥ 0.92 时零 token 返回历史根因，命中后反向填充 L1。
- **三档复核门控**（`AUTO_CONFIRMED` / `NEEDS_CONFIRMATION` / `NEEDS_HUMAN_REVIEW`）- 置信度 + 证据双判，借鉴 PagePilot。
- **正负双向反馈飞轮** - few-shot 正样本 + anti-pattern 负样本（「该这么答」/「别这么答」），均注入下一次 L3 prompt。
- **技术栈升级** - JDK 21 + Spring Boot 4.1 + Spring AI 2.0。

## 技术栈

| 领域 | 选型 |
|------|------|
| 框架 | Spring Boot 4.1 + Java 21 |
| LLM | Spring AI 2.0（OpenAI 兼容协议，DashScope/DeepSeek 可切换） |
| L1 缓存 | Caffeine（生产可换 Redis） |
| L2 向量 | PgVector（默认关闭，渐进式解锁） |
| 消息队列 | Kafka（采集层第三入口，默认关闭） |
| 弹性 | Resilience4j |
| 度量 | Micrometer + Prometheus |

## 开源致谢

本项目借鉴了以下优秀开源项目的设计思想：

- **PostHog** error_tracking：指纹算法版本化、embedding rendering 元数据、周报结构
- **Arvo-AI/aurora**：RCA 后动作自动化、知识库积累思想
- **salesforce/PyRCA**：RCA 评估方法论
- **PagePilot**（支付宝商家中心测试团队）：置信度分档门控（自动 / 待确认 / 转人工）与 known-failures 失败模式自学习库；本项目的 L3 三档复核级别 + 正负双向反馈飞轮（few-shot + anti-pattern）即借鉴于此

## 许可证

基于 [MIT License](https://opensource.org/licenses/MIT) 发布。