日志监视器-自动错误检测和积压日志创建
一个全面的系统，可以自动监控应用程序日志、检测错误、分析代码，并使用MCP（模型上下文协议）和AI代理创建GitHub项目积压项。
目录
______________________________________________________________________
架构概述
Log Watcher系统构建在一个分层架构之上，该架构结合了日志聚合、智能分析和自动化任务管理。该系统以连续循环的方式运行，每5分钟监控一次日志，并在检测到错误时自动创建待办事项。
该架构遵循MCP（模型上下文协议）模式，其中：
- MCP服务器 公开工具/功能
- MCP客户端 （编排层）连接到多个服务器并协调工具使用
- LLM代理 使用可用的MCP工具执行智能分析
┌─────────────────────────────────────────────────────────────┐
│ Application Services │
│ (Generating logs with service labels) │
└───────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Loki │
│ (Log Aggregation & Storage) │
│ - External log storage service │
│ - Provides LogQL query API │
└───────────────────────┬─────────────────────────────────────┘
│
│ HTTP API (LogQL)
▼
┌─────────────────────────────────────────────────────────────┐
│ MCP Servers (Tool Providers) │
│ │
│ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │ Loki Pooler │ │ GitHub MCP Server │ │
│ │ MCP Server │ │ (Official) │ │
│ │ │ │ │ │
│ │ Tool: log_query() │ │ Tools: │ │
│ │ │ │ - search_code() │ │
│ │ Queries Loki API │ │ - get_file_contents()│ │
│ │ Returns log data │ │ - list_projects() │ │
│ │ │ │ - create_issue() │ │
│ └──────────────────────┘ └──────────────────────┘ │
└───────────────────────┬─────────────────────────────────────┘
│
│ MCP Protocol (stdio)
▼
┌─────────────────────────────────────────────────────────────┐
│ Orchestration Layer (MCP Client + LLM Agent) │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ MCP Client │ │
│ │ - Connects to multiple MCP servers │ │
│ │ - Manages tool discovery and execution │ │
│ │ - Handles communication protocol │ │
│ └───────────────────────┬─────────────────────────────┘ │
│ │ │
│ ┌───────────────────────▼─────────────────────────────┐ │
│ │ LLM Agent (GPT-5.2) │ │
│ │ │ │
│ │ Capabilities: │ │
│ │ • LLM Review: Analyzes logs, investigates code │ │
│ │ • Uses log_query() from Loki Pooler MCP Server │ │
│ │ • Uses GitHub tools from GitHub MCP Server │ │
│ │ • Creates/updates backlog items │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ - Schedules execution (every 5 minutes) │
│ - Coordinates workflow between tools │
│ - Makes intelligent decisions │
└───────────────────────┬─────────────────────────────────────┘
│
│ GitHub API
▼
┌─────────────────────┐
│ GitHub Project │
│ Backlog Items │
│ (Created/Updated) │
└─────────────────────┘为什么是这种架构？
该架构遵循 MCP（模型上下文协议） 模式，它提供了几个关键好处：
- 关注点分离:
- 每个MCP服务器都是专门的工具提供商 - 编排层侧重于协调，而不是实施 - 明确日志查询、代码访问和项目管理之间的界限
- 模块化和可扩展性:
- 易于添加新的MCP服务器（例如Jira、Slack、监控工具） - 每个服务器都可以独立开发、部署和更新 - 工具可通过MCP协议发现并自我记录
- 可重复使用性:
- Loki Pooler MCP服务器可供其他应用程序使用 - GitHub MCP Server是官方维护的工具 - 无需重新实现GitHub API集成
- 协议标准化:
- 所有工具通过MCP协议（stdio）进行通信 - 无论工具实现如何，界面都保持一致 - 易于交换的实现（例如，不同的日志查询服务器）
- AI代理灵活性:
- LLM代理可以发现和使用任何可用的工具 - Agent根据上下文决定使用哪些工具 - 没有硬编码的工作流-代理适应可用功能
流程说明:
- Loki → 洛基普尔MCP服务器：直接HTTP连接，因为Loki Pooler需要查询Loki的API
- MCP服务器→ 业务流程层：MCP协议（stdio），因为这是MCP服务器通信的标准方式
- 业务流程层：包含MCP客户端（工具路由器）和LLM代理（工具用户），因为它们协同工作-客户端在代理使用工具时管理连接
______________________________________________________________________
系统流量
高级工作流
- 日志收集：应用程序日志持续发送到Loki
- 预定投票：系统每5分钟向Loki查询一次最近的错误日志
- 错误检测：系统过滤并识别错误条目
- 代码分析：AI代理分析代码库以找到根本原因
- 待办事项列表创建：自动创建或更新GitHub项目待办事项列表项
详细的分步流程
┌─────────────────────────────────────────────────────────────────┐
│ SYSTEM EXECUTION CYCLE │
└─────────────────────────────────────────────────────────────────┘
1. SCHEDULER TRIGGER (Every 5 minutes)
│
├─> Orchestration Layer starts agent execution
│
2. LOG QUERY PHASE
│
├─> LLM Agent requests log data
│ ├─> MCP Client routes call to Loki Pooler MCP Server
│ ├─> Loki Pooler MCP Server queries Loki API (HTTP)
│ ├─> Filters logs by service name
│ ├─> Retrieves logs from last 5 minutes
│ └─> Returns formatted log data to LLM Agent
│
3. ERROR ANALYSIS PHASE (If errors found)
│
├─> LLM Review Agent receives log data
│ ├─> Analyzes error messages
│ ├─> Extracts stack traces
│ ├─> Identifies error patterns
│ └─> Determines error context
│
4. CODE INVESTIGATION PHASE (If errors found)
│
├─> LLM Agent requests code investigation
│ ├─> MCP Client routes calls to GitHub MCP Server
│ ├─> Agent uses search_code() tool → Finds relevant files
│ ├─> Agent uses get_file_contents() tool → Reads source code
│ ├─> Agent analyzes code to identify file and line numbers
│ └─> Agent extracts code snippets causing errors
│
5. BACKLOG MANAGEMENT PHASE (If errors found)
│
├─> LLM Agent requests backlog management
│ ├─> MCP Client routes calls to GitHub MCP Server
│ ├─> Agent uses list_projects() tool → Finds target project
│ ├─> Agent uses list_issues() tool → Checks for duplicates
│ ├─> Agent uses create_issue() tool → Creates new backlog OR
│ └─> Agent updates existing backlog item if duplicate found
│
6. COMPLETION
│
└─> Wait 5 minutes, then repeat from step 1______________________________________________________________________
图层分解
1.洛基（原木）
目的：集中式日志聚合和存储系统
描述:
- Loki是一个水平可扩展、高可用的日志聚合系统
- 从应用程序服务收集日志
- 存储带有标签的日志（例如。，
service,environment,level) - 提供用于日志检索的LogQL查询接口
主要特点:
- 高效的日志存储和索引
- 基于标签的日志过滤
- 时间范围查询
- 高可用性和可扩展性
配置:
- 需要一个正在运行的Loki实例
- 服务日志必须标记为
service标签 - 可通过HTTP API端点访问
______________________________________________________________________
2.MCP服务器（工具提供商）
目的：通过MCP协议公开专用工具/功能
建筑：MCP服务器是公开工具的独立进程。编排层连接到多个MCP服务器以访问其工具。
2.1洛基普尔MCP服务器
目的：作为MCP工具提供日志查询功能
位置: mcp-server-log-query/
组件:
log_query.py：查询Loki API的核心函数main.py：FastMCP服务器暴露log_query工具
功能:
- 使用LogQL语法查询Loki
- 按服务名称筛选日志
- 检索过去5分钟的日志（可配置）
- 返回带有日志条目、时间戳和元数据的格式化JSON
MCP工具: log_query()
- 输入：无（使用环境变量）
- 输出：带有日志结果的JSON字符串
- 查询模式:
{service=""} - 连接：对Loki的直接HTTP API调用
关键文件:
mcp-server-log-query/
├── log_query.py # Loki query implementation
├── main.py # MCP server with log_query tool
├── Dockerfile # Container build configuration
└── docker-compose.yml # Docker deployment config2.2 GitHub MCP服务器（官方）
目的：提供GitHub存储库和项目管理功能
描述:
- GitHub上的官方GitHub MCP服务器
- 展示全面的GitHub API工具
- 处理身份验证和API通信
使用的关键MCP工具:
search_code()：搜索存储库代码get_file_contents()：读取源代码文件list_projects()：列出GitHub项目create_issue()：创建待办事项list_issues()：检查重复项- 还有更多的GitHub操作
整合:
- 通过MCP协议（stdio）连接
- 使用GitHub个人访问令牌进行身份验证
- 作为Docker容器运行
______________________________________________________________________
3.编排层（MCP客户端+LLM代理）
目的：协调所有MCP工具并管理智能代理工作流程
位置: mcp-client/
组件:
mcp_agent.py：主编排脚本config.json：MCP服务器配置
建筑: 编排层由两个协同工作的主要组件组成：
- MCP客户端：管理与MCP服务器的连接
- LLM代理：使用MCP服务器提供的工具
MCP客户责任:
- 从加载MCP服务器配置
config.json - 建立与多个MCP服务器的连接：
- log：洛基普尔MCP服务器 - github：GitHub MCP服务器（官方）
- 发现每台服务器上的可用工具
- 代表代理执行工具调用
- 处理MCP协议通信（stdio）
LLM代理人职责:
- 基于OpenAI的GPT-5.2模型
- 通过提示接收工作流指令
- 对使用哪些工具做出明智的决定
- 分析日志数据和代码
- 协调多步骤工作流程
工作流执行:
步骤1：查询日志
- 客服电话
log_query()来自Loki Pooler MCP服务器的工具 - MCP客户端将呼叫路由到相应的服务器
- Loki Pooler查询Loki API并返回格式化日志
- 代理接收过去5分钟的错误日志
步骤2：错误分析 （如果发现错误）
- 代理使用LLM功能分析日志数据
- 提取错误消息、堆栈跟踪和上下文
- 识别错误类型和模式
- 确定错误严重程度和影响
步骤3：代码调查 （如果发现错误）
- 代理调用GitHub MCP工具(
search_code,get_file_contents) - MCP客户端将调用路由到GitHub MCP服务器
- 代理接收源代码文件并确定根本原因
- 提取文件路径、行号和代码段
步骤4：待办事项管理 （如果发现错误）
- 代理调用GitHub MCP工具(
list_projects,list_issues) - 检查现有积压项目以防止重复
- 使用创建新的待办事项列表项
create_issue工具 - 如果错误仍然存在，则更新现有项目
调度:
- 启动后立即运行
- 每5分钟执行一次（可配置）
- 优雅地处理错误并继续运行
主要特点:
- 多服务器工具协调
- 智能工作流编排
- 错误处理和日志
- 可配置的执行间隔
______________________________________________________________________
4.LLM评审（能力，而不是单独的一层）
备注：LLM Review不是一个单独的架构层。这是一个 能力 业务流程层中的LLM代理。
目的：智能日志分析和代码调查功能
描述:
- 这是LLM代理执行的智能分析
- 使用GPT-5.2模型来理解和分析数据
- 决定何时使用哪些工具
- 综合来自多个来源的信息
能力:
- 错误模式识别
- 代码上下文理解
- 根本原因分析
- 重复检测逻辑
- 自然语言理解
______________________________________________________________________
5.GitHub项目待办列表创建者（功能，而不是单独的层）
备注GitHub项目待办列表创建器不是一个单独的架构层。这是一个 能力 由GitHub MCP Server工具提供，由LLM代理使用。
目的：自动化积压项目创建和管理能力
描述:
- 此功能由LLM代理使用GitHub MCP Server工具实现
- 代理智能地决定何时创建/更新待办事项
- 协同使用多个GitHub工具
工具使用:
list_projects()：查找目标项目list_issues()：检查现有项目create_issue()：创建新的待办事项get_file_contents()：包括代码引用
待办事项结构:
- 标题：简要错误描述（由代理生成）
- 描述：错误详细信息、代码片段、文件路径（由代理合成）
- 标签：自动分类
- 参考文献：源代码文件和行号的链接
______________________________________________________________________
入门指南
先决条件
- 码头工人：用于运行MCP服务器
- Python 3.12+：适用于MCP客户端
- 洛基实例：运行和可访问
- GitHub账号：使用个人访问令牌
- OpenAI API密钥：LLM代理
所需的环境变量
适用于MCP服务器（Loki Pooler）
LOKI_URL：指向您的Loki实例的URL（例如。，http://localhost:3100)SERVICE_NAME：要监视的服务的名称（例如。，my-app)
用于MCP客户端（编排）
GITHUB_REPOSITORY：存储库名称（例如。，my-org/my-repo)GITHUB_OWNER：GitHub用户名或组织GITHUB_PROJECT：积压项目的项目名称GITHUB_PERSONAL_ACCESS_TOKEN：具有仓库和项目权限的GitHub PATOPENAI_API_KEY：LLM的OpenAI API密钥
______________________________________________________________________
配置指南
步骤1：配置MCP服务器（Loki Pooler）
1.1构建Docker镜像
导航到MCP服务器目录：
cd mcp-server-log-query构建Docker镜像：
docker build -t mcp-log-query:latest .或者使用docker compose：
docker-compose build1.2配置环境变量
创建 .env 文件在 mcp-server-log-query/:
LOKI_URL=http://your-loki-instance:3100
SERVICE_NAME=your-service-name1.3测试MCP服务器
在本地运行服务器进行测试：
docker run -i --rm \
-e LOKI_URL=http://your-loki-instance:3100 \
-e SERVICE_NAME=your-service-name \
mcp-log-query:latest服务器应启动并等待stdio输入。
1.4推送到容器注册表（可选）
如果使用远程Docker镜像：
docker tag mcp-log-query:latest your-registry/mcp-log-query:latest
docker push your-registry/mcp-log-query:latest更新 docker-compose.yml 或 config.json 使用您的图像名称。
______________________________________________________________________
步骤2：配置MCP客户端（编排层）
2.1安装依赖项
导航到MCP客户端目录：
cd mcp-client创建虚拟环境：
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate安装所需的软件包：
pip install mcp-use langchain-openai python-dotenv2.2配置环境变量
创建 .env 文件在 mcp-client/:
# GitHub Configuration
GITHUB_REPOSITORY=your-org/your-repo
GITHUB_OWNER=your-org
GITHUB_PROJECT=Your Project Name
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
# OpenAI Configuration
OPENAI_API_KEY=sk-your-openai-key-here2.3配置MCP服务器
复制示例配置：
cp config.example.json config.json编辑 config.json:
{
"mcpServers": {
"github": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN}",
"-e",
"GITHUB_TOOLSETS=all",
"-e",
"GITHUB_TOOLS=all",
"ghcr.io/github/github-mcp-server"
]
},
"log": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--pull",
"always",
"-e",
"LOKI_URL",
"-e",
"SERVICE_NAME",
"your-registry/mcp-log-query:latest"
],
"env": {
"LOKI_URL": "${LOKI_URL}",
"SERVICE_NAME": "${SERVICE_NAME}"
}
}
}
}重要配置说明:
- Docker镜像名称：替换
your-registry/mcp-log-query:latest使用您的实际图像名称 - 环境变量：The
${VARIABLE}语法将从您的.env文件 - GitHub 令牌：确保您的令牌具有以下权限：
- repo （完全控制） - read:org （如果使用组织项目） - project （完全控制）
2.4验证配置
通过运行快速检查来测试配置：
# test_config.py
import json
import os
from dotenv import load_dotenv
load_dotenv()
with open("config.json", "r") as f:
config = json.load(f)
print("MCP Servers configured:")
for server_name in config["mcpServers"]:
print(f" - {server_name}")
print("\nEnvironment variables:")
print(f" GITHUB_REPOSITORY: {os.getenv('GITHUB_REPOSITORY')}")
print(f" GITHUB_OWNER: {os.getenv('GITHUB_OWNER')}")
print(f" GITHUB_PROJECT: {os.getenv('GITHUB_PROJECT')}")
print(f" LOKI_URL: {os.getenv('LOKI_URL')}")
print(f" SERVICE_NAME: {os.getenv('SERVICE_NAME')}")______________________________________________________________________
用法
运行系统
启动MCP客户端
从 mcp-client/ 目录：
python mcp_agent.py该系统将：
- 初始化与两台服务器的MCP连接
- 启动AI代理
- 启动后立即运行
- 继续每5分钟跑步一次
期望输出
[2024-01-15 10:00:00] Initializing agent...
[2024-01-15 10:00:01] Agent initialized. Starting scheduler. Running every 5 minutes.
Press Ctrl+C to stop.
--------------------------------------------------------------------------------
[2024-01-15 10:00:01] Starting agent run...
[2024-01-15 10:00:05] Agent run completed.
[Agent response with log analysis and backlog creation details]
--------------------------------------------------------------------------------
[2024-01-15 10:05:01] Starting agent run...
...停止系统
按 Ctrl+C 优雅地停止代理调度程序。
______________________________________________________________________