darshannere/tracea

## 📸 截图 | 控制面板 | Sessions | 问题 | |-----------|----------|--------| |  |  |  | | 实时 | 大脑 | |------|-------| |  |  | ## ✨ 为什么选择 tracea？ 大多数 AI 可观测性工具都是**云端托管的 SaaS**，会将你的 agent 数据发送到别人的服务器上。tracea 与众不同： | | 云端 SaaS | **tracea** | |---|---|---| | **数据所有权** | ❌ 他们的服务器 | ✅ **你的服务器** | | **框架锁定** | ❌ 厂商 SDK | ✅ **传输层补丁** —— 兼容任何框架 | | **规则** | ❌ 隐藏/黑盒 | ✅ **YAML 规则** —— 可检查、可版本控制 | | **成本** | ❌ 按席位/按事件定价 | ✅ **免费且开源** | | **告警** | ❌ 有限的集成 | ✅ **Slack + 通用 webhooks** —— 路由到任何地方 | ## 🚀 快速开始 ### Docker（推荐） ``` git clone https://github.com/darshannere/tracea.git cd tracea docker-compose up --build ``` - Server: `http://localhost:8080` - 控制面板: `http://localhost:5173` - API key：打印在日志中 + 写入 `./data/api_key.txt` ### 本地开发 **1. 后端** ``` pip install -e "." cp .env.example .env mkdir -p data cp tracea/server/detection/defaults/detection_rules.yaml data/ cp tracea/server/alerts.yaml data/ export $(grep -v '^#' .env | xargs) uvicorn tracea.server.main:app --host 0.0.0.0 --port 8080 --workers 1 ``` **2. 控制面板（单独的终端）** ``` cd dashboard npm install npm run dev ``` 打开 `http://localhost:5173` 并粘贴你的 API key。 **3. 发送事件** ``` API_KEY=$(cat data/api_key.txt) curl -X POST http://localhost:8080/api/v1/events \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "events": [{ "event_id": "evt-001", "session_id": "sess-001", "agent_id": "my-agent", "sequence": 1, "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "type": "chat.completion", "provider": "openai", "model": "gpt-4o", "role": "user", "content": "Hello, world!", "duration_ms": 120, "tokens_used": {"input": 10, "output": 5, "total": 15}, "cost_usd": 0.0003 }] }' ``` 刷新控制面板 —— 你的 session 会立即出现。 **4. 接入你的 agents** 安装 Python SDK 并运行设置向导： ``` pip install tracea tracea init ``` 这会创建 `~/.tracea/config.json`，包含你的服务器 URL、API key 和用户 ID，以便所有插件和 SDK 共享同一配置。 有关各个 agent 的 hook 安装，请参见 [tracea-plugins/](tracea-plugins/)。 ## 🏗️ 架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ tracea Server (FastAPI + SQLite WAL) port 8080 │ │ ├── Ingest API → Batch writer → SQLite │ │ ├── Detection Engine → YAML rules → Issues table │ │ ├── RCA Worker → OpenAI / Anthropic / Ollama │ │ └── Alert Dispatcher → Slack / Webhooks │ └─────────────────────────────────────────────────────────────┘ ▲ │ HTTP ┌─────────────────────────────────────────────────────────────┐ │ tracea Dashboard (React 18 + Vite) port 5173 │ │ ├── Sessions, Events, Issues, Agents │ │ ├── Cost / Token / Duration charts (Recharts) │ │ └── Settings editor for rules & alerts │ └─────────────────────────────────────────────────────────────┘ ▲ │ SDK / MCP / Hooks ┌─────────────────────────────────────────────────────────────┐ │ Your Agents │ │ ├── Python SDK (httpx patch) → OpenAI, Anthropic, Azure │ │ ├── tracea-mcp (stdio JSON-RPC) → Claude Code, Cursor │ │ └── Native hooks → Claude Code, Gemini CLI, Kimi, OpenCode│ └─────────────────────────────────────────────────────────────┘ ``` ## 🧩 功能 ### 🔍 Session 追踪 自动追踪 LLM 调用、工具执行、错误和 session 生命周期。通过传输层拦截兼容任何框架。 ### 📊 实时控制面板 React 控制面板，展示成本趋势、token 使用情况、耗时分布、session 健康状况和 agent 明细。 ### 🚨 问题检测 支持通过 YAML 配置的检测规则，用于检测： - 工具错误与任务失败 - 高成本与高延迟 - 频率限制与重复调用 - 死循环与空响应 规则在保存时热重载 —— 无需重启服务器。 ### 🧠 AI 驱动的 RCA 由 LLM 驱动的根本原因分析（RCA）： - **OpenAI** —— GPT-4o 等 - **Anthropic** —— Claude Sonnet 等 - **Ollama** —— 本地、免费、私密 默认禁用。云端后端会显示警告横幅。 ### 📡 告警路由 将问题路由到 Slack 或通用 HTTP webhooks： - 按目标进行速率限制 - 去重（60 秒窗口） - 指数退避重试（尝试 3 次） - 用于永久性故障的死信表 ## 🔌 Agent 集成 | Agent | 集成方式 | 自动捕获 | 安装 | |-------|-------------|---------------|---------| | **Claude Code** | 原生 hooks | ✅ 所有工具 | `tracea-hook.sh` + `settings.json` | | **Gemini CLI** | 原生 hooks | ✅ 所有工具 | `tracea-hook.py` + `settings.json` | | **Kimi CLI** | 原生 hooks | ✅ 所有工具 | `tracea-hook.py` + `config.toml` | | **OpenCode** | 插件系统 | ✅ 所有工具 | `tracea-plugin.ts` → `~/.opencode/plugins/` | | **OpenClaw** | 插件 hooks | ✅ 所有工具 | `openclaw.json` | | **Cursor** | MCP | ⚠️ 显式调用 | `tracea-mcp` | | **Cline** | MCP | ⚠️ 显式调用 | `tracea-mcp` | | **Zed** | MCP | ⚠️ 显式调用 | `tracea-mcp` | | **Python 脚本** | SDK | ✅ 所有 LLM 调用 | `pip install tracea` | 完整设置指南请参见 [tracea-plugins/](tracea-plugins/)。 ## ⚙️ 配置 复制示例环境变量文件并进行调整： ``` cp .env.example .env ``` | 变量 | 描述 | 默认值 | |----------|-------------|---------| | `TRACEA_DB_PATH` | SQLite 数据库路径 | `./data/tracea.db` | | `TRACEA_API_KEY_FILE` | API key 读写路径 | `./data/api_key.txt` | | `TRACEA_DATA_DIR` | 配置目录（规则、告警） | `./data` | | `TRACEA_RULES_PATH` | 检测规则 YAML | `./data/detection_rules.yaml` | | `TRACEA_ALERTS_PATH` | 告警路由 YAML | `./data/alerts.yaml` | | `TRACEA_RCA_BACKEND` | `disabled` / `openai` / `anthropic` / `ollama` | `disabled` | | `TRACEA_AUTH_MODE` | `disabled` 或 `api_key` | `disabled` | | `TRACEA_USER_ID` | 用于多用户控制面板的团队成员 ID | — | | `TRACEA_DEV_MODE` | `1` = 绕过身份验证（仅限本地） | — | ### 开发模式 为了实现零阻力的本地开发： ``` TRACEA_DEV_MODE=1 uvicorn tracea.server.main:app --host 0.0.0.0 --port 8080 ``` **切勿在生产环境中使用。** ## 🛠️ 开发 ``` # Backend 测试 pytest tests/ # SDK 测试 cd sdk-python && pytest # MCP 测试 cd tracea-mcp && pytest # Dashboard cd dashboard && npm run build ``` ## 📦 项目结构 ``` tracea/ ├── tracea/ # FastAPI backend │ ├── server/ │ │ ├── main.py # App entry point │ │ ├── db.py # SQLite + WAL │ │ ├── routes/ # API routes │ │ ├── detection/ # Rule engine + watcher │ │ ├── rca/ # RCA worker + LLM backends │ │ └── alerts/ # Alert dispatcher │ └── server/migrations/ # Schema migrations ├── dashboard/ # React 18 + Vite dashboard ├── sdk-python/ # Python SDK ├── tracea-mcp/ # MCP server ├── tracea-plugins/ # Agent hook plugins ├── data/ # SQLite + config (runtime) ├── docker-compose.yml └── .env.example ``` ## 📝 许可证 MIT —— 详情请参阅 [LICENSE](LICENSE)。

标签：AI代理, API集成, Docker, LLM追踪, Python, 可观测性, 安全防御评估, 无后门, 自托管, 请求拦截, 逆向工具