JinDaGe - logstash-mcp-server MCP Details

article

README

🚀 Logstash MCP 服务器

这是一个用于与 Logstash 实例进行交互的模型上下文协议（MCP）服务器。该服务器提供了全面的工具，用于监控和确定 Logstash 实例的性能瓶颈。

🚀 快速开始

运行 Web UI

启动 Web 界面：

python3 web_ui.py

打开浏览器并访问：

http://localhost:5001

Web UI 截图

✨ 主要特性

监控工具

节点信息：获取 Logstash 版本、构建信息和设置。
节点统计：JVM、进程和管道指标。
管道统计：监控单个或所有管道的性能。
热点线程：通过线程分析调试性能问题。
健康检查：进行全面的健康评估并提供建议。
连接检查：详细诊断与 Logstash 的连接情况。

管理工具

管道重新加载：重新加载特定的管道配置。
插件列表：查看所有已安装的 Logstash 插件。
JVM 统计：详细的内存和垃圾回收指标。
Grok 模式：列出可用于日志解析的 Grok 模式。

📦 安装指南

安装依赖项：

pip install -r requirements.txt

设置环境变量（可选）：

export LOGSTASH_API_BASE="http://your-logstash-host:9600"

💻 使用示例

基础用法

# MCP 服务器将自动分析：
# - JVM 内存使用情况
# - 管道性能
# - 队列统计
# - 提供优化建议

高级用法

# 监控特定管道性能
# 获取详细统计信息以进行故障排除
# 跟踪事件处理速率和错误

性能调试

# 使用热点线程分析来识别瓶颈
# 监控 JVM 统计信息以查找内存问题
# 跟踪管道路队列使用情况

📚 详细文档

Web UI 功能

交互式仪表板：可视化界面，可访问所有 Logstash 监控工具。
实时监控：检查连接性、节点统计信息和管道性能。
健康分析：全面的健康检查，提供可视化反馈。
管道管理：查看单个或所有管道的统计信息。
性能调试：热点线程分析和 JVM 统计信息。
插件管理：浏览已安装的 Logstash 插件。

Web UI 配置

Web UI 使用与 MCP 服务器相同的配置：

默认 Logstash URL：http://localhost:9600
可使用 LOGSTASH_API_BASE 环境变量进行覆盖
Web 界面运行地址：http://localhost:5001

自定义 Logstash URL 示例：

export LOGSTASH_API_BASE="http://your-logstash-host:9600"
python3 web_ui.py

可用工具（共 12 个）

`logstash_check_connectivity`

检查与 Logstash 实例的连接，提供详细的连接状态、响应时间和错误处理信息。

返回：连接状态、URL、版本、主机、响应时间、错误详情和故障排除建议

`logstash_node_info`

获取 Logstash 节点信息，包括版本、构建信息和设置。

`logstash_node_stats`

获取全面的节点统计信息，包括 JVM、进程和管道指标。

参数：human（布尔值，默认：true）

`logstash_pipelines_stats`

获取所有 Logstash 管道的统计信息。

参数：human（布尔值，默认：true）

`logstash_pipeline_stats`

获取特定管道的统计信息。

参数：id（字符串，必需），human（布尔值，默认：true）

`logstash_hot_threads`

获取热点线程信息，用于调试性能问题。

参数：threads（整数，默认：3），human（布尔值，默认：true）

`logstash_plugins`

列出所有已安装的 Logstash 插件。

`check_backpressure`

检查队积压指标，以监控管道性能和拥塞情况。

参数：human（布尔值，默认：true）

`logstash_health_check`

进行全面的健康检查，提供分析和建议。

`logstash_jvm_stats`

获取详细的 JVM 统计信息，用于内存分析。

参数：human（布尔值，默认：true）

`logstash_health_report`

从 Logstash 获取详细的健康报告。

`flow_metrics`

获取详细的流量指标，包括吞吐量、积压和工作线程并发情况。

参数：human（布尔值，默认：true）

健康检查分析

健康检查工具会分析以下内容：

连接验证：在进行其他检查之前测试与 Logstash 的连接。
JVM 内存使用情况：如果堆使用率超过 80% 则发出警告。
管道性能：检测有过滤但无输出事件的管道。
队列使用情况：识别可能影响性能的大队列大小。

快速启动命令

使用 python3 logstash_mcp_server.py 启动服务器后，可使用以下 JSON - RPC 命令：

1. 初始化（首次必需）

{"jsonrpc": "2.0", "id": 0, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}

2. 检查连接性

{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "logstash_check_connectivity", "arguments": {}}}

3. 健康检查

{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "logstash_health_check", "arguments": {}}}

4. 列出所有工具

{"jsonrpc": "2.0", "id": 3, "method": "tools/list"}

5. 获取节点信息

{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "logstash_node_info", "arguments": {}}}

与 ELK 栈集成

此 MCP 服务器设计为与 Elasticsearch 诊断工具配合使用，可帮助：

监控向 Elasticsearch 集群提供数据的 Logstash 性能。
识别可能导致索引延迟的管道瓶颈。
优化 Logstash 配置，以提高集群性能。

根据 Elasticsearch 集群分析显示的高分片计数，确保 Logstash 管道针对高效索引模式进行了优化。

错误处理

服务器包括全面的错误处理功能，用于处理以下情况：

与 Logstash API 的连接失败。
无效的管道 ID。
API 响应错误。
网络超时。
提供详细的错误消息和故障排除建议。

测试

运行测试套件以验证一切正常：

python3 test_mcp_server.py

测试套件包括：

服务器初始化测试。
工具列表验证。
模拟健康检查测试。
错误处理验证。

安全考虑

服务器会连接到 Logstash API 端点。
确保 MCP 服务器和 Logstash 之间有适当的网络安全措施。
如果 Logstash 实例需要认证，请考虑进行认证。
监控 API 访问日志以进行安全审计。

⚠️ 重要提示

此仓库是通过 AI 生成的代码，未经过充分测试。使用时请自行承担风险。