mongodb-log

MongoDB Log & Metric Analyzer 项目设计

1．文档定位

本文说明当前版本实际采用的产品设计、系统架构、数据流、功能拆分、核心算法、资源边界和验证方式。它面向以下读者：

• 需要理解项目为什么这样设计的维护者。
• 准备新增功能、修复问题或审查实现的开发者。
• 需要先建立完整上下文，再对项目进行二次改写的 AI。

本文描述的是「当前实现」，不是早期设想。发生冲突时，判断优先级为：

1. 当前源码和自动化测试。
2. CLAUDE.md 中的硬约束。
3. 本文与用户指南。
4. README.md 中的概览说明。

2．项目目标与边界

2.1 核心目标

项目解决的是运维人员在个人电脑上离线分析 MongoDB 诊断文件的问题，包含两个相互独立但共用运行外壳的工作区：

• MongoDB Log：解析结构化日志、旧版单行日志和 .gz 日志，生成慢查询统计、运行诊断和脱敏 Markdown 报告。
• MongoDB Metric：解析 MongoDB FTDC 文件，建立紧凑索引，再按指标组查询并绘制时间序列。

2.2 明确不做的事情

• 不连接 MongoDB 实例，不执行查询或管理命令。
• 不依赖数据库、对象存储、消息队列或外部 AI 服务。
• 不自动上传日志、FTDC、分析结果或遥测数据。
• 不提供账号、授权、多租户或公网服务能力。
• 不根据单条日志或单个指标自动断言故障根因。
• 不在产品层开放 FTDC 单指标查询、原始值分页和完整指标导出。
• 不在升级后自动重算历史任务。

2.3 运行假设

• 单机、单用户、本地使用。
• 默认监听 127.0.0.1:18080。
• 发布时只要求 Java 17；Node.js 和 npm 仅用于源码构建。
• 启动脚本统一设置 -Xms128m -Xmx2g。
• 业务元数据持久化到本地 JSON／JSONL，FTDC 额外保存源文件副本和二进制索引。

3．总体设计原则

3.1 本地优先

浏览器页面、后端服务、分析计算和文件存储全部位于同一台电脑。页面通过本机 REST API 访问 Spring Boot 服务，不引入远端依赖。

3.2 流式和有界优先

Log 按行读取，FTDC 按 BSON 文档和 Block 读取。系统尽量只保留聚合值、固定容量明细和当前解码 Block，避免把完整输入展开到内存。

3.3 精确统计与有界展示分离

需要业务精确性的统计基于全部有效数据计算；只有明细保留和图表点数受限。例如：

• 八档耗时分布基于全部慢查询。
• Top 5000 使用固定容量最小堆精确选取。
• FTDC 的 min、max、avg 和全零判断基于全部有效点。
• FTDC 图表最多返回 1,200 点，降采样不改变完整统计值。

3.4 缺失值不等于零

MongoDB 不同版本、日志格式和配置提供的字段不同。所有可选指标都按字段是否存在判断；缺失字段展示为「日志未提供」，不会补成零。

3.5 发布完整结果，不暴露半成品

JSON、JSONL、FTDC catalog 和索引先写临时文件，再原子移动到正式位置。FTDC 工作目录在全部文件建索引成功后才整体发布到任务目录。

3.6 证据和结论分离

页面提供测量值、聚合结果和排查线索，但不把线索写成确定根因。例如出现 COLLSCAN 时，只建议结合索引、过滤条件和集合规模继续核对。

4．系统架构

浏览器
└── Vue 3 单页应用
    ├── MongoDB Log 工作区
    ├── MongoDB Metric 工作区
    └── 内存与数据维护入口
            │ HTTP／JSON／Multipart
            ▼
Spring Boot 本地服务
├── web        REST 接口、参数校验、统一错误响应
├── task       上传、任务状态、异步执行、恢复与删除
├── parser     Log 与 FTDC 格式解析
├── analysis   聚合、诊断、FTDC 序列查询与降采样
├── report     脱敏 Markdown 报告
├── storage    JSON／JSONL、catalog、二进制索引
└── config     单线程执行器、解析器装配、浏览器启动
            │
            ▼
本地 data 目录
├── Log 任务元数据和结果
└── FTDC 任务元数据、源副本、catalog 和 blocks.idx

4.1 后端分层职责

包	核心职责	设计要点
config	组装解析器、创建任务执行器、启动浏览器	只负责运行配置，不承载业务逻辑
web	REST API、参数校验、错误映射	Controller 不直接实现解析算法
task	任务创建、状态迁移、后台执行、清理	Log 与 FTDC 生命周期分开建模
parser	输入格式识别和字段提取	解析失败显式分类，不静默丢弃
analysis	统计、诊断、序列合并与降采样	完整统计与有界输出分离
storage	任务与结果持久化	临时文件加原子移动，删除前校验路径
report	生成 AI 可读报告	只读取已持久化结果，并统一脱敏

4.2 前端分层职责

位置	核心职责
App.vue	工作区切换、Log 任务状态、结果视图和全局页面状态
api/*.js	REST 请求、错误消息和文件下载
components/	Log 上传、任务列表、统计、诊断、慢查询详情、通用图表
components/ftdc/	FTDC 上传、任务列表、指标组选取和图表
utils/format.js	时间、字节、时长、百分比格式化
utils/queryExplanation.js	基于实际字段生成保守的查询解读

5．公共任务模型与并发设计

5.1 状态机

Log 和 FTDC 都采用相同的四态模型：

QUEUED → RUNNING → COMPLETED
                 ↘ FAILED

• 创建接口在上传副本保存成功后返回 202 Accepted 和 QUEUED 任务。
• 后台执行器开始处理时写入 RUNNING 和开始时间。
• 所有结果发布、临时文件清理完成后才写入 COMPLETED。
• 解析、存储或清理失败时写入 FAILED 和可读错误消息。
• 应用启动时发现残留的 QUEUED 或 RUNNING 任务，会标记为失败，不继续使用可能不完整的中间状态。

5.2 单线程任务执行器

TaskExecutorConfig 创建一个守护单线程执行器。Log 分析和 FTDC 建索引共用它，因此上传任务按队列顺序处理，不会同时争抢大量内存和磁盘带宽。

5.3 FTDC 公平串行许可

FTDC 建索引、序列查询以及内部分页／导出组件共用 FtdcOperationGate。它使用公平的单许可 Semaphore，确保重型 FTDC 操作串行执行，并在异常后释放许可。

5.4 前端轮询

• Log 和 FTDC 页面每秒读取一次活动任务状态。
• pending 标记阻止同一任务的状态请求重叠。
• 版本号和 AbortController 用于丢弃旧任务、旧指标组或已关闭详情抽屉的迟到响应。
• 这是单用户页面的轻量竞态控制，不是分布式任务协调。

6．MongoDB Log 功能设计

6.1 上传与任务创建

功能

用户可以为任务命名，并上传普通文本、结构化 JSON 或 .gz 日志。多个文件按选择顺序合并为一个分析任务。

设计点

• 前端一次最多选择 20 个文件；当前 Log 后端负责非空校验和格式拒绝，但没有独立的文件数量上限校验。
• 服务端拒绝 .zip、.bz2、.xz 和 .7z；.gz 根据文件名后缀进入 GZip 解码。
• Multipart 请求上限为 12 GB，包含表单开销。
• 原文件名会去除路径片段和换行符；存储名增加四位上传顺序前缀。
• 上传内容先复制到 data/work/<task-id>，用户原文件不被修改。
• 文件全部保存成功后才创建任务并进入后台队列；保存失败会尽力清理工作目录。

核心类

• TaskService
• AnalysisTask
• TaskInputFile

6.2 文件流式读取

功能

后台逐文件、逐行解析日志，并持续更新处理字节数和行数。

设计点

• TaskRunner 用 BufferedReader 读取 UTF-8 文本。
• .gz 文件通过 GZIPInputStream 解压，不生成完整解压副本。
• CountingInputStream 统计原始上传副本的已读字节。
• 每处理 1,000 行保存一次进度，文件结束时再保存一次。
• 成功或失败后都清理 data/work/<task-id>；清理失败会使任务进入失败状态，避免界面声称已经完整结束。

核心类

• TaskRunner
• CountingInputStream

6.3 格式路由与解析结果

功能

同一任务可以包含 MongoDB 结构化日志和旧版单行日志。

设计点

CompositeLogParser 去除 BOM 后检查行首：

• 以 { 开头时交给 StructuredLogParser。
• 其他内容交给 LegacyLogParser。

每一行都返回 ParseOutcome，状态为：

状态	含义	是否可以携带部分字段
SUCCESS	已完整解析当前支持字段	是
PARTIAL	主体可用，但部分字段无效或缺失	是
SKIPPED	空行或非 MongoDB 日志	否
FAILED	看起来是目标格式，但结构或关键字段无效	否

错误码进入 parseErrors 聚合，页面披露失败、部分解析和跳过数量。

6.4 结构化日志解析

功能

解析 MongoDB 4.4 及以上常见结构化日志字段，同时兼容字段增减。

设计点

• 使用 MongoDB BSON Document.parse，支持 Extended JSON。
• t.$date、日期对象、数字时间戳和 ISO 时间字符串都可转换为 UTC Epoch Milliseconds。
• 从 s、c、id、ctx、msg 和 attr 提取日志信封与业务字段。
• 仅当 msg 等于 Slow query 时认定慢查询，避免把其他带耗时字段的日志混入统计。
• 操作类型优先取 attr.command 的第一个命令名，再回退到 attr.type 或 command。
• 支持 find、aggregate、insert、update、delete、getMore、findAndModify、createIndexes 等命令的模式提取。
• durationMillis、cpuNanos、reslen 只接受可精确转换的非负整数。
• remote 和 client 会去除端口；IPv6 方括号地址单独处理。
• svc、tags 和 truncated 进入信封元数据，用于数据质量诊断。
• 不按服务器版本号决定字段是否可读，未知字段保留在 attributes 中供诊断和详情使用。

核心类

• StructuredLogParser
• ParsedLogEntry
• LogEnvelopeMetadata

6.5 旧版单行日志解析

功能

解析旧版时间、级别、组件、上下文和消息格式，并从消息中提取慢查询、连接和心跳信息。

设计点

• 先匹配固定日志头，再解析时间戳。
• 支持 find、aggregate、insert、update、remove、getMore、findAndModify 和 createIndexes。
• BalancedDocumentExtractor 按花括号深度提取嵌套命令，并正确忽略字符串中的花括号和转义引号。
• 旧版未加引号的键会转成可解析 JSON；ObjectId、NumberLong、Timestamp 等 BSON 构造器替换为占位值。
• 找不到完整命令主体时保留已解析字段，并返回 PARTIAL。
• NETWORK 日志用于连接统计，不误判为慢查询。
• 仅匹配消息中的 Heartbeat failed，不会把 checkpoint 恢复文本误判成心跳失败。

核心类

• LegacyLogParser
• BalancedDocumentExtractor

6.6 查询模式归一化

功能

把字面值不同但结构相同的查询归入同一模式。

设计点

• Map 的键按字典序排序，保证输出稳定。
• 数组保留元素顺序和结构。
• 所有标量替换为 ?。
• 无可用模式时返回 {}。
• 模式分组键不是单独的模式文本，而是 Namespace + 操作类型 + 模式，避免跨集合或跨操作混合。

核心类

• QueryPatternNormalizer

6.7 慢查询聚合

功能

基于所有成功提取耗时的慢查询生成统计。

输出

• 总行数和四类解析状态计数。
• 慢查询总数和总耗时。
• 八档耗时分布。
• 操作类型、Namespace、查询模式、执行计划、客户端和 CPU 聚合。
• Namespace 响应字节总量。
• 小时连接数平均值。
• 日志时间范围和心跳失败次数。

八档耗时区间

Key	范围
lt_100ms	<100ms
100ms_500ms	100ms-500ms
500ms_1s	500ms-1s
1s_3s	1s-3s
3s_10s	3s-10s
10s_30s	10s-30s
30s_60s	30s-60s
gte_60s	>=60s

边界采用左闭右开，最后一档无上限。每档记录数量、占比、总耗时、平均耗时和最大耗时。

CPU 设计

• 只有实际出现 cpuNanos 时，汇总才标记 cpuAvailable=true。
• CPU 纳秒先换算为毫秒，再除以本次操作耗时得到比例。
• insert、update、delete、find 按 10％ 区间统计；旧版 remove 映射到 delete。
• 耗时为零或 CPU 缺失的记录不进入比例桶。
• CPU 比例不是服务器整体 CPU 利用率，页面和报告都不把差值解释为确定等待时间。

连接数设计

旧版连接消息中的当前连接数按 UTC 小时聚合为平均值。没有样本的小时不会自动补零。

核心类

• AnalysisAccumulator
• DurationDistribution
• AnalysisSummary
• AggregateStat
• PatternStat

6.8 Top 5000 与 Top 50

全局 Top 5000

TopSlowQueryCollector 使用固定容量最小堆：

• 每条有效慢查询只进行一次入堆比较。
• 堆满后，只有比当前最小值更重要的记录才替换堆顶。
• 最终按耗时降序输出。
• 耗时相同按更早时间、文件顺序和行号稳定排序。

这保证 Top 5000 是从全部慢查询中精确选取，不是抽样。

Top 50 查询模式

• 所有模式先按出现次数降序排名，再稳定选择前 50。
• 每个模式在分析过程中独立保留自己最慢的一条样本。
• 即使该样本不在全局 Top 5000 中，仍随 PatternStat 持久化。
• 历史任务可能没有独立模式样本，页面必须显示缺失说明，不能伪造明细。

6.9 运行诊断

功能

运行诊断独立于慢查询汇总，输出到 diagnostics.json，不会改变旧的 summary.json 口径。

诊断范围

• 严重级别和组件计数。
• 警告、错误、致命错误事件。
• 连接建立／结束、认证、客户端应用和 Driver。
• 复制集、心跳、选举、拓扑、同步源和网络事件。
• 慢查询效率线索。
• 结构化字段覆盖率、服务角色、版本、截断、标签和文件内时间乱序。

有界策略

• 异常事件类型最多 500 种，每类最多 3 条消息样本。
• 复制集事件类型最多 100 种。
• 时间线最多 2,000 点；超限时桶宽度翻倍并合并。
• 应用和 Driver 使用固定容量 100 的近似计数器，最终各展示 Top 20。
• 查询框架容量为 50，服务角色和版本容量各为 20。
• 慢查询线索最多保留 50 条。
• 查询 shape 去重最多记录 10,000 个。

近似计数器满时对全部候选计数减一并移除零值，这是有界高频项估计，不应解释为完整精确枚举。

慢查询线索规则

当前实现会标记：

• COLLSCAN。
• 文档扫描／返回比或索引键扫描／返回比不小于 100。
• 返回为零且扫描文档数不小于 1,000。
• 存储读取耗时或查询规划耗时不小于总耗时的 50％。
• 写关注、Flow Control、锁、分片响应、鉴权缓存、执行队列和 Oplog 提交等待。
• 额外排序、使用临时磁盘和查询执行落盘。

这些规则只生成线索，不生成自动根因。

核心类

• DiagnosticAccumulator
• LogDiagnostics

6.10 结果持久化和恢复

目录

data/
├── tasks-index.json
├── tasks/<task-id>/
│   ├── metadata.json
│   ├── summary.json
│   ├── diagnostics.json
│   └── top-slow-queries.jsonl
└── work/<task-id>/

设计点

• tasks-index.json 支持任务列表快速恢复。
• 每个任务的 metadata.json 保存独立状态。
• 汇总、诊断和慢查询明细分文件存储，便于历史格式兼容。
• JSON 和 JSONL 都通过同目录 .tmp 文件发布，再尝试原子移动。
• 普通日志原文不保存；只有全局 Top 5000 和 Top 50 独立样本会携带原始慢查询行。
• 读取历史任务时不会凭空补算新统计；缺失 diagnostics.json 时接口明确提示重新上传。

核心类

• TaskRepository
• FileTaskRepository

6.11 结果页面

慢查询分析视图

• 解析质量提示和错误码计数。
• 可切换图表／数据表的统计区块。
• 八档耗时分布。
• Top 50 查询模式，可按展示列排序，并通过集合／模式关键字、操作类型和执行计划文本组合筛选。前端先按次数选取 Top 50，再取条件交集并排序；文本匹配忽略大小写与首尾空格，按普通子串处理，不使用正则表达式。筛选只影响展示，不改变已选中的 Top 50 集合、持久化结果或报告；结果数据替换时清空条件。
• 操作、Namespace、客户端、执行计划、CPU 和连接趋势。
• 按 Namespace 分组的慢查询散点图。
• 右侧详情抽屉，展示保留字段、原始慢查询行和基于实际字段的解释。
• 面板宽高保存在浏览器 localStorage，可单独拖动或一键恢复默认布局。

慢查询详情

• 散点只加载 timestamp + duration + queryId 的轻量数据。
• 用户点击后才请求单条完整详情。
• 后端重新解析保留的原始行，补充消息 ID、级别、组件、上下文和消息。
• 表格分页支持 Namespace、操作、执行计划和最低耗时筛选，每页最多 200 条。

竞态处理

• 切换任务、关闭抽屉或选择新点会使旧请求失效。
• 迟到响应只有在版本号和当前选中对象仍匹配时才能更新页面。

6.12 Markdown 报告

功能

用户可下载当前 Log 任务的 Markdown 报告，供人工检查或交给 AI 二次分析。

内容

• 任务和文件信息。
• 解析质量、慢查询统计和耗时分布。
• 操作、Namespace、模式、计划、客户端和 CPU 聚合。
• 运行异常、连接、复制集和慢查询线索。
• 规范化查询模式和受限明细。

隐私设计

• 不导出完整命令、完整 attributes 或全部原始日志。
• 遮盖 MongoDB URI、IPv4、IPv6、邮箱和常见密钥字段。
• 用户身份字段和客户端地址使用别名或遮盖值。
• 任务名、文件名、Namespace、查询模式和计划摘要仍可能包含业务信息，外发前必须人工复核。
• 报告时间统一使用 UTC，页面显示使用浏览器本地时区。

核心类

• MarkdownReportService

7．MongoDB Metric 功能设计

7.1 上传与任务创建

功能

一个任务上传 1～20 个非空 FTDC 文件，文件按内容验证，不依赖扩展名。

设计点

• 后端明确校验文件数量和空文件。
• 文件按上传顺序命名为 0000-...、0001-...，顺序同时决定重复时间戳的优先级。
• 上传副本先保存到 data/ftdc/work/<task-id>/source。
• 建索引成功后，整个工作目录发布为正式任务目录。

核心类

• FtdcTaskService
• FtdcTask
• FtdcTaskRunner

7.2 外层 BSON 扫描

功能

逐文档读取 FTDC 文件，定位 type=1 指标 Block。

设计点

• FtdcFileReader 使用 FileChannel 按偏移读取 BSON 长度和当前文档。
• 单个 BSON 文档最多 16 MiB。
• 拒绝非法长度、截断文档、缺少数值 type 和缺少二进制 data。
• 文件至少包含一个合法指标 Block，否则整个文件失败。
• 元数据文档可以跳过，但指标 Block 必须完整验证。

7.3 Block 解压和结构验证

功能

解压一个 Block，读取 baseline、Schema、样本数量、delta 偏移和零游程信息。

硬上限

项目	上限
声明解压长度	10,000,000 字节
单 Block 样本数	100,000
指标数 × 样本数	1,000,000

设计点

• 在数组分配和解码循环前检查规模。
• zlib 实际输出必须与声明长度完全一致。
• 压缩流结束后不允许存在剩余数据。
• baseline BSON 长度、属性数量、delta 数量和展平结果必须一致。
• uvarint 截断或溢出立即失败。
• RLE 零游程不能越过声明的指标单元格数量。
• delta 流必须恰好消费完，不能有尾随数据。
• Schema 必须包含 start 时间指标。

Baseline 展平

• 嵌套文档使用 / 拼成指标路径。
• 数组索引也进入路径。
• Timestamp 展平为 /t 和 /i。
• Int32、Int64、Double、Decimal128、DateTime 和 Boolean 转为 long。
• 非数值字段不进入指标 Schema。

核心类

• FtdcFileReader
• FtdcBlockScanner
• FtdcBaselineFlattener
• FtdcVarIntReader

7.4 Catalog 与二进制索引

功能

建索引阶段只保存以后定位和恢复指标列所需的信息，不保存完整展开时间序列。

Catalog

catalog.json 保存：

• 所有 Schema 及其指标路径。
• Schema 合并后的指标列表。
• Block 数、样本数和整体时间范围。
• 指标 ID。ID 是指标路径 SHA-256 的前 8 字节十六进制形式，稳定且不暴露路径字符到 URL。

blocks.idx

二进制索引保存：

• 源文件清单、大小和 SHA-256。
• Schema 清单。
• 每个 Block 的文件编号、序号、文件偏移和 BSON 文档长度。
• 声明解压长度、压缩长度、Schema ID 和 delta 数量。
• 起止时间、全局点偏移。
• 每列 baseline、delta 起点和初始零游程状态。

发布方式

• Block 记录先写入 blocks.spool，避免在建索引时把全部 Block 索引留在 Java 对象中。
• 完成后写出正式 blocks.idx。
• catalog.json 通过临时文件加原子移动发布。
• 工作目录最后整体移动到 data/ftdc/tasks/<task-id>。

核心类

• FtdcCatalog
• FtdcBlockIndex
• FtdcIndexWriter
• FtdcIndexReader

7.5 指标分组

功能

产品只允许按指标组查询，避免用户一次触发大量零散请求。

分组规则

• 默认使用指标路径的父路径作为组名。
• WiredTiger cache、transaction 和系统 netstat 等高密度路径使用专门前缀细分。
• start、end、globalLock/totalTime 和部分内部时间戳不作为业务组展示。
• serverStatus/ 前缀从展示名称中去除。
• 组 ID 是组名 SHA-256 的前 8 字节十六进制形式。
• 单组最多 200 个指标，超限时拒绝查询。

核心类

• FtdcMetricGroups

7.6 按需列解码

功能

查询一个指标组时，每个 Block 只恢复时间列和该组实际存在的指标列。

设计点

• 先从二进制索引中选择相关 Block 和列位置。
• 同一查询内复用源文件 FileChannel，一个源文件只在首次需要时打开。
• 每个 Block 解压一次，再为选中列创建 ColumnDecoder。
• 未选中的列不创建 baseline、offset、zero 或完整序列对象。
• 解码器按点推进，不构造 Map<String, List<Long>>。

完整性校验

查询前重新核对每个源副本的文件大小和 SHA-256。副本被外部改动后立即拒绝查询，避免索引指向错误数据。

核心类

• FtdcMetricDecoder
• FtdcIndexReader
• FtdcSeriesService

7.7 多文件时间序列合并

功能

多个 FTDC 文件可以包含交叠时间范围，查询结果必须按时间有序且去重。

设计点

• 每个源文件建立一个按 Block 推进的迭代器。
• 使用优先队列按时间戳合并多个文件。
• 同一时间戳出现多份值时，文件编号更小者优先，也就是上传顺序更靠前的文件优先。
• 输出时间戳严格递增，重复点不会进入后续统计和图表。
• 指标组中的某个指标在当前 Schema 不存在时，只跳过该指标，不影响同组其他指标。

7.8 原始值与相邻差值

原始值

直接返回 FTDC 恢复后的累计值或即时值。

相邻差值

• 每个指标独立保存前一个有效原始值。
• 第一个点没有前值，因此输出 null。
• 后续点输出 current - previous。
• 差值使用 Java long 运算语义，不额外推断计数器重置或溢出原因。

7.9 完整统计与降采样

完整统计

遍历全部有效点时同步计算：

• min
• max
• average
• allZero

这些值不从降采样结果反推。

降采样

• 每个指标最多返回 1,200 个图表点。
• 点数未超过上限时保留全部点。
• 超限后保留首点、尾点，以及时间桶内的最小值和最大值。
• 同一时间桶的最值按真实时间顺序写入，避免视觉顺序错误。
• 最终仍按时间排序并去重，绝不超过接口上限。

7.10 时间断裂

功能

当 FTDC 采样中断时，在图表中插入 null，防止折线跨越空白时间连接。

算法

• 对相邻时间间隔进行最多 4,096 个样本的有界抽样。
• 先求初步中位数，并过滤大于其 10 倍的异常间隔。
• 对剩余间隔再求典型中位数。
• 大于典型间隔 3 倍的间隔视为断裂候选。
• 最多保留与图表点数预算相匹配的最大断裂。
• 在断裂内部插入一个 null 点，前端悬浮值显示 -。

7.11 Metric 前端工作流

任务阶段

• 上传后显示排队、建索引进度、Block 数、指标数、样本数和时间范围。
• 任务完成后加载指标组目录。

查询阶段

• 支持关键字筛选指标组和多选。
• 「一键选择核心指标组」按固定组名和前缀选择常用连接、网络、操作、内存、锁、WiredTiger 和系统指标。
• 浏览器按用户选择顺序串行请求每个组。
• 每个组返回后立即加入页面，不等待全部组完成。
• 单组失败显示在原位置，并继续查询后续组。
• 切换原始值／相邻差值会重新查询已选组。

图表阶段

• 每个组可折叠／展开。
• 可在合并图和拆分图之间切换。
• 可隐藏／显示全零指标。
• 支持对所有已加载组执行批量展开、关闭、隐藏全零和显示全零。
• 前端只根据后端提供的 null 判断断裂，不从降采样点间距自行猜测。

7.12 内部保留但未公开的组件

源码中存在单指标查询、原始值分页和 GZip CSV 导出服务：

• FtdcSeriesService.series
• FtdcSeriesService.page
• FtdcMetricExportService

当前 FtdcTaskController 没有为它们声明 REST 路由，前端也没有入口。因此它们属于内部已测试组件，不属于当前发布的产品功能。文档、AI 改写和 API 兼容性判断都必须保持这个区分。

7.13 FTDC 存储布局

data/ftdc/
├── tasks-index.json
├── tasks/<task-id>/
│   ├── metadata.json
│   ├── catalog.json
│   ├── blocks.idx
│   └── source/<uploaded-file>
└── work/<task-id>/

FTDC 必须保留源副本以支持后续按需解码，因此磁盘占用与上传文件总量接近，并额外增加 catalog 和索引。删除任务只删除应用托管副本，不触碰用户原文件。

8．系统级功能

8.1 JVM 堆内存显示

/api/system/memory 返回 JVM 已用堆、最大堆和使用百分比。页面启动后立即读取，并每 5 秒刷新。该数值是 JVM 堆，不代表进程总 RSS 或系统内存。

8.2 清空全部数据

• 用户必须在页面二次确认。
• 后端先检查全部 Log 和 Metric 任务；只要存在排队或运行任务，整次清理直接拒绝，不先删一部分。
• 允许清理的状态只有 COMPLETED 和 FAILED。
• 删除逻辑拒绝非法任务 ID、符号链接和异常存储路径，降低越界删除风险。

8.3 单任务删除

• Log 和 Metric 任务列表都允许删除终态任务。
• 活动任务不可删除。
• 删除失败时任务记录保留，便于修复文件权限后重试。
• 页面只有在 API 成功后才从列表移除任务。

8.4 自动打开浏览器

应用启动完成后尝试打开当前配置的本地地址。桌面能力不可用或打开失败只写警告，不影响服务继续运行。可通过 mongodblog.open-browser=false 禁用。

9．REST API 设计

9.1 Log API

方法	路径	用途	关键限制
POST	/api/tasks	创建 Log 任务	Multipart，文件不能为空
GET	/api/tasks	获取任务列表	按创建时间倒序
GET	/api/tasks/{taskId}	获取任务状态	活动任务用于轮询
DELETE	/api/tasks/{taskId}	删除终态任务	活动任务返回冲突
GET	/api/tasks/{taskId}/summary	获取慢查询汇总	仅已完成任务
GET	/api/tasks/{taskId}/diagnostics	获取运行诊断	历史任务可能不存在
GET	/api/tasks/{taskId}/slow-queries	分页筛选 Top 5000	size 为 1～200
GET	/api/tasks/{taskId}/slow-query-points	获取散点轻量数据	只返回保留明细
GET	/api/tasks/{taskId}/slow-queries/{queryId}	获取单条详情	重新解析保留原始行
GET	/api/tasks/{taskId}/report.md	下载 Markdown 报告	UTF-8 附件

9.2 Metric API

方法	路径	用途	关键限制
POST	/api/ftdc-tasks	创建 FTDC 任务	1～20 个非空文件
GET	/api/ftdc-tasks	获取任务列表	按创建时间倒序
GET	/api/ftdc-tasks/{taskId}	获取任务状态	活动任务用于轮询
DELETE	/api/ftdc-tasks/{taskId}	删除终态任务	活动任务返回冲突
GET	/api/ftdc-tasks/{taskId}/groups	获取指标组	任务必须完成
GET	/api/ftdc-tasks/{taskId}/groups/{groupId}/series	查询指标组	maxPoints 为 1～1,200，view 为 raw 或 delta

9.3 系统 API

方法	路径	用途
GET	/api/system/memory	获取 JVM 堆使用情况
DELETE	/api/system/data	清空全部终态任务和托管数据

9.4 错误模型

统一返回：

{
  "code": "INVALID_REQUEST",
  "message": "可读错误信息",
  "details": {}
}

主要映射：

HTTP 状态	错误码	场景
400	INVALID_REQUEST	参数、文件数量或范围无效
404	NOT_FOUND	任务、指标组或明细不存在
409	TASK_NOT_READY	请求未完成任务的结果
409	TASK_ACTIVE	删除活动任务或活动时清空数据
413	UPLOAD_TOO_LARGE	Multipart 超过 12 GB
422	FTDC_FORMAT_ERROR	FTDC 内容损坏或超出格式边界
500	TASK_DELETE_FAILED	托管数据删除失败

10．构建与交付设计

10.1 技术栈

• Java 17。
• Spring Boot 3.4.5。
• MongoDB BSON 5.2.1。
• Vue 3.5、Vite 8、Element Plus 2.14、ECharts 6.1。
• JUnit／Spring Boot Test 和 Vitest。

10.2 构建链路

mvn clean package
├── clean：删除旧构建产物
├── prepare-package：在 web 目录执行 npm ci
├── prepare-package：执行 npm run build
├── copy-resources：复制本次前端静态资源
└── spring-boot-maven-plugin：生成可执行 JAR

最终产物为 target/mongodb-log-analyzer.jar。发布目录还应包含三个平台启动脚本。

11．测试与验证设计

11.1 后端单元测试重点

• 结构化和旧版日志字段解析。
• BOM、异常 JSON、无效数值和缺失字段。
• 查询模式归一化、命令嵌套和 BSON 构造器。
• 八档耗时边界、Top 5000 精确性和稳定排序。
• Top 50 独立样本、CPU 比例和小时连接数。
• 运行诊断的有界事件、时间线、字段覆盖和版本兼容。
• FTDC BSON、zlib、uvarint、RLE、规模上限和尾随数据拒绝。
• 二进制索引读写、错误 magic、截断和源文件变化。
• 原始值／差值、跨文件合并、降采样、断裂和完整统计。
• 串行许可、任务恢复、原子持久化和删除防护。
• 报告内容、历史兼容和敏感值遮盖。

11.2 后端集成测试重点

• 上传到完成、结果查询和删除的完整流程。
• 空文件、过多 FTDC 文件和无效参数。
• 慢查询分页边界。
• 删除活动任务、非法 ID、符号链接和权限失败。
• JVM 内存接口和全量清理的全有或全无行为。

11.3 前端测试重点

• 工作区记忆、任务轮询和旧响应竞态。
• 解析异常披露、缺失值与零值区分。
• 图表／表格切换、Top 50 排序、组合筛选边界和完整长模式显示。
• 散点轻量加载、详情抽屉、请求失效和重试。
• 诊断按需加载与报告下载。
• FTDC 多组串行增量渲染、单组失败隔离和请求取消。
• 时间断裂 null 显示、全零隐藏和面板批量控制。
• 面板尺寸保存、损坏 localStorage 和小屏布局。
• 删除确认和内存轮询。

11.4 验证命令

mvn test
cd web
npm test -- --run
npm run build
cd ..
mvn clean package

真实 FTDC 验收测试需要外部样本路径，未配置时会按条件跳过；不能把跳过描述成已使用真实样本验证。

12．安全、隐私和删除边界

12.1 网络边界

• 默认只绑定回环地址。
• 当前 API 没有认证，不应直接暴露到局域网或公网。
• 如改变监听地址，必须同时重新设计认证、CSRF、上传限流和数据隔离。

12.2 路径边界

• 上传文件名只取 basename。
• 工作目录和任务目录使用规范化绝对路径，并检查解析结果仍位于预期根目录。
• 删除前使用 NOFOLLOW_LINKS 检查符号链接和文件类型。
• 任务 ID 只允许字母、数字、下划线和连字符，且首字符必须是字母或数字。

12.3 数据边界

• Log 工作副本在终态前清理。
• FTDC 源副本是查询必需数据，任务删除前一直保留。
• 删除操作只覆盖应用 data 目录内的托管数据。
• 报告脱敏是降低风险，不是数据匿名化保证。

13．当前权衡和已知限制

13.1 为简单性接受的权衡

• 使用单工作线程而不是复杂调度器，牺牲并行吞吐换取内存可预测性。
• 使用本地文件而不是数据库，适合单用户但不支持跨进程事务和查询优化。
• Log 慢查询分页会读取完整 Top 5000 JSONL 后在内存筛选，规模固定且实现简单。
• 前端状态集中在组件中，没有引入额外状态管理库。
• 指标组由路径规则生成，没有单独维护领域元数据仓库。

13.2 需要维护者特别注意的限制

• Log 前端限制 20 个文件，但后端目前没有同等文件数量限制；不能把前端约束误写成服务端强制约束。
• AnalysisAccumulator 的操作、Namespace、模式、计划和客户端聚合 Map 会随不同值数量增长；原始行是流式的，但这些核心聚合并非全部固定容量。
• 运行诊断中的高基数 Top 值是近似计数，不能与精确汇总混为一谈。
• 单指标分页和导出服务存在于源码，但没有产品接口。
• 所有时间序列数值使用 long，Double baseline 会按 Java 规则转为 long，不保留小数。
• 相邻差值不自动识别计数器重置。
• 历史任务只兼容读取已有字段，不自动按新版算法重算。

14．修改设计时的同步要求

任何功能改动都必须同时检查以下位置：

1. CLAUDE.md 中是否存在不可破坏的统计、资源或隐私约束。
2. 后端模型、解析器、聚合器、存储格式和 Controller 是否一致。
3. 前端 API、状态、组件和错误提示是否一致。
4. 单元测试、集成测试和前端测试是否覆盖新边界。
5. README.md、用户指南、本文和 AI 改写指南是否需要同步。
6. 已完成并验证后是否更新 ROADMAP.md。

更具体的 AI 开发流程见 AI 二次改写指南 。

This site is open source. Improve this page.