内容
# SigNoz SRE 指挥中心
> **团队：** Rudra Khairnar & Het Patel — KPGU
> **活动：** [SigNoz 黑客马拉松](https://github.com/SigNoz/signoz) — 赛道 2：信号与仪表盘
> **问题：** SRE 团队缺乏一个统一的 SLO 仪表盘，具有 AI 驱动的分析和自动化的微服务事件恢复功能。
**完整的可见性 + AI 分析 + 自动恢复。所有功能都在 SigNoz 上。**
## 架构
```
服务 → OpenTelemetry → SigNoz（查询构建器 + 仪表盘 + 警报）
↓
┌─────────────────────────────────┴─────────────────────────────────┐
│ │
▼ ▼
AI 代理（LangGraph + Ollama） 自动恢复 Webhook
（自然语言查询） （警报时重启 docker）
```
查看 [ARCHITECTURE.md](./ARCHITECTURE.md) 以获取完整的图表。
## 功能
### 第一阶段 — SigNoz 部署
- 通过 [Foundry](https://github.com/SigNoz/foundry) 部署 SigNoz，并启用 MCP 服务器
- 单命令设置：`foundry deploy`
### 第二阶段 — 3x 手动 OTel 仪表盘
| 服务 | 语言 | 框架 | 端口 |
|---------|----------|-----------|------|
| FastAPI | Python | FastAPI + OpenTelemetry SDK | 8001 |
| Express | Node.js | Express + OpenTelemetry SDK | 3001 |
| Go Worker | Go | net/http + OpenTelemetry SDK | 8081 |
- 跨越所有 3 个服务的分布式跟踪
- 带有 trace_id 相关性的结构化日志
- 自定义 span 属性（slo_tier, service.name）
- otel-demo-lite 与其一起运行（15+ 补充服务）
### 第三阶段 — SLO 指挥中心仪表盘 + 警报
**仪表盘（7 个面板）：**
- SLO 目标仪表盘（当前 SLO %）
- 错误预算剩余（%）
- 活动警报计数
- 监控服务（共 18 个）
- p99 延迟时间序列
- 错误率时间序列
- 跟踪日志相关性表格
**3 个警报规则：**
| 警报 | 条件 | 严重程度 | 渠道 |
|-------|-----------|----------|---------|
| 错误预算警告 | EB < 50% | 警告 | Slack |
| 错误预算严重 | EB < 20% | 严重 | PagerDuty + 邮件 |
| 燃烧率严重 | 燃烧率 > 2x，持续 10 分钟 | 严重 | Webhook |
### 第四阶段 — AI 代理（MCP + LangGraph + Ollama）
- **SigNoz MCP 服务器**：结构化工具访问 SigNoz（服务、跟踪、日志、警报、仪表盘、指标、文档）
- **LangGraph 代理**：`create_react_agent`，带有推理循环
- **本地 LLM**：Ollama（llama3.2:3b）— 无需 API 密钥
- **Streamlit UI**：聊天界面，访问地址：http://localhost:8501
**示例查询：**
- "哪些服务正在运行？"
- "给我看过去一小时的错误跟踪"
- "我的 p99 延迟是多少？"
- "检查 express-svc 的日志"
### 第五阶段 — 自动恢复
- **Webhook 接收器**（Flask，端口 9000）：监听警报 Webhook，重启失败的容器
- **AI 集成**：代理可以通过 MCP 检测问题并触发 `signoz_remediate` 工具
- **故障模拟器**：淹没或停止服务以演示恢复循环
- **流程**：警报 → Webhook → `docker compose restart` → 验证恢复
## 安装指南
完整的从零开始的指南。预计时间：**30–45 分钟**。
### 前提条件
| 工具 | 版本 | 检查命令 | 安装链接 |
|------|---------|---------------|--------------|
| Docker Desktop | 29+ | `docker --version` | [docker.com](https://www.docker.com/products/docker-desktop/) |
| Foundry CLI | ≥0.2 | `foundryctl version` | [github.com/SigNoz/foundry](https://github.com/SigNoz/foundry) |
| Ollama | ≥0.31 | `ollama --version` | [ollama.com](https://ollama.com/download) |
| Python | 3.12+ | `python --version` | [python.org](https://www.python.org/downloads/) |
| Git | 任意 | `git --version` | [git-scm.com](https://git-scm.com/downloads) |
### 步骤 1 — 克隆仓库
```bash
git clone https://github.com/rudrakhairnar16-bit/signoz-sre-command-center.git
cd signoz-sre-command-center
```
### 步骤 2 — 部署 SigNoz（通过 Foundry）
```bash
foundry deploy
```
这将启动：SigNoz UI、ClickHouse、PostgreSQL、OTel Collector、MCP 服务器、Alert Manager。
等待所有容器变为健康状态（`docker ps` 显示 `healthy` for `signoz-signoz-0`）。
**验证：** 打开 http://localhost:8080 — 您应该看到 SigNoz 登录页面。
登录：`admin@signoz.io` / `Admin@12345!`
> **注意：** Foundry 拉取镜像并配置容器。首次运行需要 5–10 分钟。
> 如果端口 8080 已被占用，请编辑 `pours/deployment/compose.yaml` 并更改端口映射。
### 步骤 3 — 拉取本地 LLM（Ollama）
```bash
ollama pull llama3.2:3b
```
这将下载一个 2 GB 的模型。AI 代理在本地使用它 — **无需 API 密钥或云积分**。
**验证：** `ollama list` 应该显示 `llama3.2:3b`。
### 步骤 4 — 创建 Docker 网络
自定义服务和 SigNoz 必须在同一个 Docker 网络上。
```bash
docker network create signoz-network 2>/dev/null || true
```
### 步骤 5 — 设置 Python 虚拟环境
```bash
python -m venv ai-agent/venv
```
**Windows：**
```bash
ai-agent\venv\Scripts\pip install -r ai-agent\requirements.txt
```
**macOS / Linux：**
```bash
ai-agent/venv/bin/pip install -r ai-agent/requirements.txt
```
这将安装：LangChain、LangGraph、Ollama Python 客户端、Streamlit、Flask、httpx 等。
### 步骤 6 — 构建和启动自定义服务
三个仪表盘的微服务形成一个请求链：
`FastAPI (Python) → Express (Node.js) → GoWorker (Go)`
```bash
cd services
docker compose up -d --build
cd ..
```
**验证所有 3 个服务正在运行：**
```bash
docker ps --filter "name=(fastapi|express|goworker)" --format "table {{.Names}}\t{{.Status}}"
```
**测试请求链：**
```bash
curl http://localhost:8001/process
```
预期响应：
```json
{"service":"fastapi-svc","express_result":{"service":"express-svc","goworker_result":{"result":"work_done","service":"goworker-svc","status":"completed"}}}
```
### 步骤 7 — 在 SigNoz 中验证可观察性数据
1. 打开 http://localhost:8080
2. 进入 **服务** 标签页 → 您应该看到至少 3 + otel-demo-lite 服务
3. 进入 **跟踪** 标签页 → 过滤 `fastapi-svc` → 跟踪应该出现（可能需要 30 秒）
4. 进入 **仪表盘** → **SLO 指挥中心** → 所有 7 个面板正在渲染
> **没有可见的服务？** 点击该端点几次：`for i in 1 2 3 4 5; do curl -s http://localhost:8001/process > /dev/null; done`。然后刷新 SigNoz。
### 步骤 8 — 注入仪表盘和警报规则
SLO 指挥中心仪表盘和 3 个警报规则存储在 PostgreSQL 中。
运行以下命令插入它们（一次性）：
```bash
# Windows (PowerShell):
powershell -Command "& { ai-agent\venv\Scripts\python -c "from mcp_tool import query_signoz; print('仪表盘准备好了')" }"
# 或通过 SigNoz UI 导入：
# 仪表盘 → 导入 JSON → 选择 dashboards/slo-command-center.json
```
> **注意：** 仪表盘在开发过程中已预先插入。如果您看不到它，请通过 `dashboards/slo-command-center.json` 手动导入 SigNoz UI。
### 步骤 9 — 启动 AI 代理
```bash
# 确保 Ollama 正在运行（它通常作为后台服务启动）
ollama serve &
# 启动 Streamlit 应用
cd ai-agent
```
**Windows：**
```bash
venv\Scripts\streamlit run app.py
```
**macOS / Linux：**
```bash
venv/bin/streamlit run app.py
```
在浏览器中打开 http://localhost:8501。
**测试它：**
- "哪些服务正在运行？"
- "给我看过去一小时的跟踪"
- "重启 fastapi-svc"
### 步骤 10 — 启动自动恢复 Webhook
打开一个 **第二个终端** 并运行：
```bash
cd signoz-sre-command-center
```
**Windows：**
```bash
ai-agent\venv\Scripts\python auto-remediation\webhook.py
```
**macOS / Linux：**
```bash
ai-agent/venv/bin/python auto-remediation/webhook.py
```
**验证：**
```bash
curl http://localhost:9000/health
# → {"status":"ok","timestamp":"..."}
```
### 步骤 11 — 运行演示
**选项 A — 仅 Webhook 测试：**
```bash
python auto-remediation/simulate-failure.py --mode webhook-only --service fastapi-svc
# → 发送一个假警报 → Webhook 重启容器
```
**选项 B — 完整的洪水 + 恢复演示：**
```bash
python auto-remediation/simulate-failure.py --mode flood --service fastapi-svc --count 500
# → 淹没服务 500 个请求 → 触发 Webhook → 容器重启
```
**选项 C — 一键 PowerShell 演示（Windows）：**
```powershell
powershell -ExecutionPolicy Bypass -File demo/demo.ps1
```
**选项 D — Bash 演示（WSL / Linux / macOS）：**
```bash
bash demo/demo.sh
```
## 关键 URL
| 服务 | URL | 目的 |
|---------|-----|---------|
| SigNoz UI | http://localhost:8080 | 仪表盘、跟踪、日志、指标 |
| AI 代理 | http://localhost:8501 | SigNoz 数据的自然语言聊天 |
| 恢复 Webhook | http://localhost:9000/health | 自动恢复端点 |
| FastAPI 服务 | http://localhost:8001/process | 入口微服务 |
| Express 服务 | http://localhost:3001/execute | 中间微服务 |
| Go Worker | http://localhost:8081/work | 叶微服务 |
## 故障排除
| 问题 | 原因 | 修复 |
|---------|-------|-----|
| `network signoz-network not found` | 网络未创建 | `docker network create signoz-network` |
| 服务无法启动 | 端口冲突 | 更改 `services/docker-compose.yaml` 中的端口 |
| MCP 返回 403 | 缺少 API 密钥 | 在 `pours/deployment/compose.yaml` 中设置 `SIGNOZ_API_KEY` |
| 代理显示“工具未找到” | Ollama 未运行 | 在启动代理之前运行 `ollama serve` |
| `go mod tidy` 失败 | Go 版本太旧 | 将 Dockerfile 更新为 `golang:latest` |
| SigNoz 中无跟踪 | 未生成流量 | 多次点击 `curl http://localhost:8001/process` |
| npm 安装失败 | 包版本错误 | 在 `services/express/` 中运行 `npm install` |
## 仓库结构
```
signoz-sre-command-center/
├── casting.yaml # Foundry 部署配置
├── pours/deployment/ # Foundry compose 输出
├── services/ # 3 个自定义仪表盘服务
│ ├── fastapi/ # Python + OTel SDK
│ ├── express/ # Node.js + OTel SDK
│ └── goworker/ # Go + OTel SDK
├── ai-agent/ # LangGraph + Ollama AI 代理
│ ├── mcp_tool.py # MCP JSON-RPC 包装器
│ ├── agent.py # LangGraph 反应代理
│ └── app.py # Streamlit 聊天 UI
├── auto-remediation/ # Webhook 接收器 + 模拟器
│ ├── webhook.py # Flask Webhook（端口 9000）
│ └── simulate-failure.py # 流量洪水 / 服务停止
├── dashboards/ # 导出的仪表盘 JSON
│ └── slo-command-center.json
├── alerts/ # 警报规则文档
├── opentelemetry-demo-lite/ # 补充演示服务
├── ARCHITECTURE.md # 系统架构图
└── README.md # 此文件
```
## 技术栈
| 类别 | 工具 |
|----------|-------|
| 可观察性 | SigNoz、OpenTelemetry、ClickHouse |
| 仪表盘 | Python OTel SDK、Node.js OTel SDK、Go OTel SDK |
| AI/ML | LangGraph、Ollama（llama3.2:3b）、Streamlit |
| 后端 | FastAPI、Express.js、Go、Python Flask |
| 基础设施 | Docker、Docker Compose、Foundry |
## 演示脚本（2 分钟）
| 时间 | 场景 |
|------|-------|
| 0:00 | 正常运行 — 绿色仪表盘，健康 SLO |
| 0:15 | 事件 — 运行故障模拟器，延迟峰值，EB 燃烧 |
| 0:35 | AI 分析 — “是什么导致延迟峰值？” → 代理诊断 |
| 0:55 | 自动恢复 — 燃烧率警报 → Webhook → 服务重启 |
| 1:15 | 恢复 — 仪表盘变绿，AI 报告影响 |
| 1:35 | 关闭 — 架构概述 |
## 团队
- **Rudra Khairnar** — 仪表盘、MCP、AI 代理、自动恢复
- **Het Patel** — 仪表盘、警报、演示、文档
