mongodb-log

MongoDB Log & Metric Analyzer 使用方法与限制

简体中文 ｜ English ｜ 返回项目首页

本文面向直接使用发布包的运维人员，说明如何启动、分析 MongoDB 日志与 Metric 文件，以及使用前必须了解的能力边界。

1．工具定位

MongoDB Log & Metric Analyzer 是在个人电脑上运行的本地离线分析工具，提供两个工作区：

• MongoDB Log：分析 MongoDB 文本日志、结构化 JSON 日志和 .gz 压缩日志，生成慢查询统计、运行诊断和脱敏 Markdown 报告。
• MongoDB Metric：分析 diagnostic.data/metrics.* FTDC 文件，建立本地索引后按指标组查看时间序列。

工具不连接 MongoDB，不需要 MongoDB、Node.js、Nacos、S3 或网络服务。应用默认只监听 127.0.0.1:18080，解析与字段解读均在本机完成。

本项目全程使用 AI 完成设计、编码、测试与文档编写。后续如需修改或扩展，建议继续使用 AI，并遵循项目规范与现有验证流程。项目虽由 AI 编程实现，但核心分析逻辑、统计口径与输出结果均已通过自动化测试、实际样本及人工复核验证。

2．运行要求

• Docker 方式：安装 Docker Desktop 或 Docker Engine，建议给容器至少 3 GB 内存。
• JAR 方式：安装 Java 17 或更高版本，并在发布目录中同时保留 mongodb-log-analyzer.jar 和 scripts 目录。
• 启动磁盘需要有足够空间存放分析结果、临时文件和 Metric 文件副本。
• Docker 镜像与启动脚本均使用 -Xms128m -Xmx2g。2 GB 是 Java 堆上限，不等于容器或进程的全部内存占用。

使用 JAR 时的标准发布目录：

mongodb-log-analyzer/
├── mongodb-log-analyzer.jar
└── scripts/
    ├── start.command
    ├── start.sh
    └── start.bat

3．启动与停止

Docker

公开镜像支持 linux/amd64 与 linux/arm64。执行：

docker run -d \
  --name mongodb-log-analyzer \
  --restart unless-stopped \
  --memory=3g \
  -p 127.0.0.1:18080:18080 \
  -v mongodb-log-analyzer-data:/app/data \
  whaleal/mongodb-log-analyzer:0.1.0

启动后访问 http://127.0.0.1:18080。执行 docker stop mongodb-log-analyzer 停止，执行 docker start mongodb-log-analyzer 再次启动。

任务数据保存在命名卷 mongodb-log-analyzer-data 中。升级镜像时可以重建容器，但要继续挂载该卷；不要执行会删除卷的 docker compose down -v。应用没有账号和授权机制，不要把容器端口直接暴露到公网。

JAR 发布包：macOS

首次使用时，在终端执行：

chmod +x scripts/start.command scripts/start.sh

之后双击 scripts/start.command。也可以在终端执行 ./scripts/start.sh。

JAR 发布包：Linux

执行：

./scripts/start.sh

JAR 发布包：Windows

双击 scripts\start.bat。

启动成功后，浏览器通常会自动打开 http://127.0.0.1:18080。如果没有自动打开，可手动访问该地址。

停止程序时，关闭启动窗口或在启动终端按 Ctrl+C。不要在任务分析或 Metric 索引建立期间直接强制结束进程；中断的任务在下次启动后会标记为失败，需要删除后重新上传。

4．MongoDB Log 使用方法

4.1 创建任务

1. 在页面顶部选择「MongoDB Log」。
2. 可填写任务名称；留空时默认使用第一个文件名。
3. 点击「选择日志文件」，选择普通文本、结构化 JSON、旧版单行日志或 .gz 文件。.zip、.bz2、.xz 和 .7z 不受支持。
4. 一个任务可合并多个非空文件，Web 页面一次最多选择 20 个文件。单次上传请求还受 12 GB 服务端上限约束。
5. 点击「开始分析」。

文件会按选择顺序流式处理。页面显示排队或分析进度，完成后可进入结果页。Log 分析与 Metric 建索引共用一个后台单线程；该线程正在处理任务时，后续 Log 分析或 Metric 建索引任务会排队，不会并行抢占内存。

4.2 查看结果

从任务列表点击「查看分析结果」。结果分为两个页签：

• 「慢查询分析」：查看失败操作、客户端、操作类型、集合、耗时分布、查询模式、执行计划、CPU、连接数和最慢查询散点。
• 「运行诊断」：查看异常日志、连接与认证、客户端应用／Driver、复制集与网络事件、慢查询效率线索和结构化字段覆盖。

使用提示：

• 图表可切换为数据表，查看精确数值。
• 指标名称后的问号用于查看单位、范围和统计口径。
• 点击最慢查询散点，可在右侧查看该条日志的字段、原文和本地解读。
• 最慢查询表支持按 Namespace、操作类型、执行计划和最低耗时筛选；后端分页每页最多返回 200 条已保留明细。
• Top 50 查询模式默认按出现次数排序；点击表头只改变已入选 50 组的展示顺序。
• 查询模式表上方可搜索集合名或查询字段，选择操作类型，并输入执行计划关键字（如 COLLSCAN）。文本搜索忽略大小写和首尾空格，多项条件取交集；显示匹配组数，点击「重置」清空条件。筛选只作用于已入选 Top 50，不会从全部模式中重新选取；切换任务后条件清空，报告仍导出原有任务聚合结果。
• 可拖动指标面板右下角调整尺寸。布局保存在当前浏览器，可通过「恢复默认布局」清除。
• 解析失败、部分解析或跳过的行会在结果页提示；统计只包含成功提取的字段。

4.3 导出报告

点击「导出 AI 分析报告」，可下载当前任务的 Markdown 报告。报告包含聚合统计、规范化查询模式和脱敏诊断信息，便于交给 AI 或人工进一步分析。

报告不会自动发送到任何 AI 服务，也不会导出完整命令、完整原始日志或 attributes。导出时会遮盖 MongoDB URI、IPv4／IPv6、邮箱，以及带 user、username、principal、password、passwd、token、secret 标签的值。任务名、文件名、Namespace、查询模式、执行计划和其他聚合字段仍会进入报告，因此导出后的文件仍应按所在组织的数据安全要求复核。

页面时间按浏览器本机时区显示；Markdown 报告中的时间使用 UTC，便于跨时区对照其他监控数据。

5．MongoDB Metric 使用方法

5.1 创建任务

1. 在页面顶部选择「MongoDB Metric」。
2. 选择 1～20 个 diagnostic.data/metrics.* 文件。
3. 点击「开始建立索引」。
4. 等待任务完成后进入 Metric 分析页。

程序按文件内容识别 FTDC，不依赖扩展名。空文件、截断文件、压缩数据损坏或不含合法指标 Block 的文件会被拒绝。

5.2 查询指标组

1. 搜索并选择一个或多个指标组，或点击「一键选择核心指标组」。
2. 点击「查询所选指标组」。
3. 程序按选择顺序逐组读取；已完成的组会立即显示，单组失败不会中断后续组。
4. 根据需要切换「原始值／相邻差值」「合并展示／分开展示」，或隐藏全零指标。
5. 时间采集出现明显断裂时，折线会在断点处断开，不会跨断裂连线。

Metric 建索引、指标查询以及其他重型操作共用串行通道。长时间显示排队通常表示已有操作正在执行，不代表页面停止响应。

多个文件出现相同时间戳时，程序优先采用上传顺序更靠前的文件。每个指标图最多返回 1,200 个点，但最小值、最大值、平均值和全零判断基于查询范围内的全部有效点，而不是降采样结果。

6．任务与本地数据

应用默认在启动目录的 data 下保存任务数据。

Log 数据

• 用户选择的原始日志不会被修改。
• 上传副本只在分析期间保存在工作目录，任务完成或失败后删除。
• 完整日志不会全部持久化。应用只保存聚合结果、全局最慢 Top 5000 明细，以及 Top 50 查询模式各自最慢的一条样本。

Metric 数据

• 用户选择的原始 FTDC 文件不会被修改。
• 为支持后续查询，应用会保留上传副本、指标目录和二进制索引。
• 应用不会保存全量展开后的时间序列，但 Metric 副本仍会持续占用磁盘。
• 每次查询前会核对索引中记录的文件大小和 SHA-256；应用托管副本被外部改动后会拒绝查询。

删除数据

• 在对应任务列表点击「删除」，只会清理应用保存的任务数据，不会删除用户原文件。
• 排队中或运行中的任务不能删除，需要等待任务结束。
• 右上角内存指示器中的全量清理会删除全部已结束的 Log／Metric 任务和应用托管数据；存在活动任务时会整体拒绝，不会只删除一部分。

7．能力与资源限制

7.1 运行边界

• 工具默认只监听本机地址，不提供账号、权限、多用户协作、远程访问或公网部署能力。
• 工具是离线文件分析器，不是 MongoDB 实时监控、告警、备份或数据库管理工具。
• 工具不连接 MongoDB，因此无法查询当前索引定义、服务器配置、实时锁、实时会话或未写入日志的状态。
• 单次上传请求的服务端上限为 12 GB。请求还包含少量表单开销，实际文件总大小应略低于该上限。

7.2 Log 分析边界

• 分析结果取决于日志实际包含的字段。缺失 cpuNanos、连接计数、扫描量或执行计划时，对应指标显示无数据，不会按零值补齐。
• 耗时区间、Top 20 和 Top 50 使用全量聚合；散点和可查看的全局慢查询明细只保留最慢 Top 5000。
• Top 50 查询模式每组只额外保留一条最慢样本，不等于保留该模式的全部原文。
• 结构化日志按已实现字段能力解析，已知诊断字段按实际出现次数统计覆盖率，额外未知字段会忽略。无法识别的行不会进入有效统计。
• 更新程序不会重新计算历史任务。要使用新版解析或诊断规则，必须重新上传原始日志。

7.3 Metric 分析边界

• 单个任务最多包含 20 个非空 FTDC 文件。
• 单个指标组最多包含 200 个指标。
• 每个指标图最多返回 1,200 个点。最小值、最大值和平均值基于完整有效点计算，图表数据会有界降采样。
• 单个 FTDC Block 的声明解压长度最多 10,000,000 字节，样本数最多 100,000，且「指标数 × 样本数」最多 1,000,000；超出上限会作为异常文件拒绝。
• 不提供产品层单指标查询入口、原始值分页或完整指标导出。
• FTDC 源副本被外部修改后，校验会失败，需要重新创建任务。

7.4 结论边界

页面提供统计结果、字段解释和排查线索，不会自动判断故障根因。高耗时、COLLSCAN、CPU 占比或连接波动都只是线索，最终结论仍需结合业务流量、索引、查询计划、MongoDB 配置、硬件和同一时段的其他监控验证。

8．常见问题

页面打不开

确认启动窗口仍在运行，并检查 Java 版本。若 18080 端口被占用，需要先关闭占用该端口的程序，再重新启动。

.gz 文件分析失败

确认文件确实采用 GZip 压缩，而不是只把其他格式改成 .gz 扩展名。

CPU 或连接图没有数据

对应字段未出现在日志中。工具会显示无数据，不代表 CPU 或连接数为零。

任务长期排队

Log 分析与 Metric 建索引共用一个后台单线程；Metric 建索引和指标组查询还共用公平串行许可。等待占用对应执行通道的任务或查询结束后，排队操作会继续执行。

Metric 文件占用磁盘

Metric 任务需要保留应用副本和索引。确认不再需要结果后，在 Metric 任务列表删除任务即可释放对应空间，用户原文件不会被删除。

Metric 文件被拒绝

程序会校验 BSON 文档、zlib 解压长度、指标与样本规模、RLE 数据和压缩流结尾。空文件、截断文件、损坏数据、声明长度不一致或没有合法指标 Block 都会明确失败；请重新获取完整的 MongoDB FTDC 原文件。

历史任务缺少新版数据

历史结果不会在升级后自动重算。重新上传原始文件，创建新任务即可应用当前版本的解析能力。

This site is open source. Improve this page.