简介
一份循序渐进的指南，帮助你打开、使用并验证 Query Regressions 界面——NoSqlStudio 内置的性能回退与异常检测器。请从第 1 步开始，按顺序读到最后。每一步都会告诉你该做什么以及你会看到什么。
如何阅读本手册
每一步都包含：
- 操作 — 具体动作（点击、输入、运行某条命令）。
- 查看 — 屏幕上应当发生的情况。这就是你的“通过 / 失败”判定标准。
- 原因 — 额外的背景说明，仅在有帮助时才有（赶时间的话可以跳过）。
什么是 Query Regressions
概念
一个稳定的指纹，类似 Oracle 的 sql_id
每种查询形态都会获得一个稳定的指纹，它在不同运行之间永远不变——与 Oracle 的 sql_id 是同样的思路。NoSqlStudio 为每个指纹学习一个滚动的baseline（基线），当同一个查询开始变得更昂贵时就触发告警：墙钟时间更慢、检查的文档更多、消耗更多 RU，或执行计划更差（例如 IXSCAN → COLLSCAN）。
概念
一个界面，三种引擎
同一个界面适用于 MongoDB、Azure Cosmos DB（Mongo API）和 AWS DocumentDB。采集是实例级的——它能看到来自每个客户端、每个数据库的慢查询，而不仅仅是你从 NoSqlStudio 运行的那些。这正是它能在维护窗口期间捕捉到未声明变更的原因。
概念
五个层级的根因分析
每条告警都分层解释：L1 变更前后的指标 · L2 执行计划差异 · L3 调查项（索引、集合统计、基数）· L4 ±5 分钟窗口内相关的 DDL/部署事件（“在它变慢之前发生了什么变更”）· L5 AI 叙述。
开始之前
你可以完全不连接任何数据库、仅用演示数据探索整个界面（阶段 1–3）。实时采集（阶段 4–6）需要一个连接，数据源取决于引擎：
- 1MongoDB — 通过
getLog:'global'读取服务器慢查询日志。适用于自托管的副本集和专用 Atlas 集群。在 Atlas 共享层级（M0/M2/M5）上不可用，因为它们会阻止getLog。 - 2Cosmos DB — 从 Azure Log Analytics 读取诊断日志。需要在 Cloud Credentials（Cosmos Optimizer）中接入 Log Analytics。
- 3DocumentDB — 从 Amazon CloudWatch Logs 读取 DocDB profiler 流。需要在集群参数组中启用 profiler、导出到 CloudWatch，并在 Cloud Credentials 中设置 AWS 凭据。
- 4第二个标签页，你可以在其中运行 shell 命令——Scratchpad 或 Mongo Shell——来生成慢查询。
完成整个演练的预计时间：约 25 分钟。
打开界面（无需数据库）
先把界面打开并加载内置演示，这样你可以在接入实时数据源之前先熟悉布局。
打开 Query Regressions
在工具栏中选择 Monitoring ▼ → Query Regressions（快捷键 Ctrl+Alt+Shift+Q）。
会打开一个新标签页，左侧是 Query Regressions 标题、一个主列表，右侧是详情面板。
加载演示数据
如果列表为空，请在空状态中点击 Load demo data。
在一个 SHOP 分组下会出现两条示例告警：一条 Plan regression — shop.orders，一条 Selectivity collapse — shop.events。标题处显示一个红色的 2 CRITICAL 徽章。
演示完全在内存中运行——没有服务器、无需权限。这是了解卡片中每个区块含义的最快方式。
选择一条告警
在列表中点击 Plan regression — shop.orders 卡片。
详情面板会填充内容。标题处显示一个 CRIT 徽章、标题，下方是 fingerprint（指纹，一个稳定的哈希值）、命名空间和发生次数。
告警的剖析
从上到下阅读详情面板的每个区块——所有引擎的布局都相同。
WHAT CHANGED（变更内容，Level 1）
一个包含 Signal · Baseline · Now · Δ 的表格。对 MongoDB/DocumentDB，指标是 p95 duration (ms)；对 Cosmos，指标是 RU。第二行显示 docs examined / returned。当出现回退时，“Now”和“Δ”列会被高亮（例如 2.6 → 197 = 75.8×）。
这就是核心要点：同一个查询如今比它自己学习到的 baseline 昂贵得多。
HOW IT CHANGED — 执行计划差异（Level 2）
变更前后的执行计划，例如 IXSCAN { userId:1, status:1 } ⇩ COLLSCAN。被删除的索引或损坏的 plan-cache 条目会立即在这里显现。
WHY — 根本原因（Level 3）
来自调查项的要点结论：集合上存在哪些索引、执行计划是否改变、plan-cache 键是否改变。每条要点用绿色（正常）或琥珀色（可疑）标注。
WHAT CHANGED NEARBY（附近的变更，Level 4）
检测时刻 ±5 分钟内的 DDL 和部署事件时间线——例如 2m before · dropIndex · shop.orders · idx_user_status。
这就是对“在它变慢之前发生了什么变更”的回答。在执行计划翻转为 COLLSCAN 前两分钟删除了一个索引，几乎可以确定就是根本原因。
QUERY SHAPE 与 AI Root Cause（Level 5）
规范化的查询形态（op、filter 字段、sort 字段），随后是一个带有模型选择器和 Run analysis 按钮的 AI Analysis 面板。
点击 Run analysis。
按钮在模型工作时会发光，然后出现一段简洁的根因叙述 + 修复建议，它是基于本条告警的事实清单撰写的。
打开详情弹窗
点击详情面板右上角的 ··· 按钮。
会打开一个弹窗，带有固定的头部（严重级别 + 标题 + 指纹）和一个可滚动的主体：真实执行的命令、一个 Explain plan 按钮以及一个 AI 区块。
概念
Command 是从慢查询源捕获到的实际命令——而非重建——因此 Explain 运行的是真实的查询形态。
建议的修复措施
底部有：Clear plan cache（对 MongoDB 的 plan-change 告警启用）、Acknowledge 和 Snooze 24h。
点击 Acknowledge，然后点击 Snooze 24h，观察列表中该告警的状态变化。
注意
Clear plan cache 会写入到实时服务器。它总是会先要求确认——在确认前请阅读对话框，尤其是在生产环境上。
范围与未声明变更防护
切换范围
在 SCOPE 栏中点击一个数据库标签（或 All databases）。
列表会过滤到所选的数据库。All databases 是默认值，也是你在维护窗口期间想要的。
检测始终在实例级运行。范围只过滤你看到的内容——它绝不会阻止引擎监视每一个数据库。
范围外的严重告警横幅
如果你缩小了范围，而一个严重回退在你过滤之外的数据库中触发，就会出现一条警告横幅：“N critical regression(s) in databases outside your filter”。
这是针对那类经典事故的防护：某次变更声称只触及数据库 X，但一个隐藏脚本改动了未声明的数据库 Y。即便你没有在看 Y，横幅也会把它浮现出来。
在 MongoDB 上进行实时采集
现在接入一个真实数据源。MongoDB 无需设置凭据——它直接读取服务器慢查询日志。
连接一个副本集或专用 Atlas 集群
将 NoSqlStudio 连接到一个 MongoDB 副本集或一个专用 Atlas 集群，然后在该连接上打开 Query Regressions。
标题处将实时状态显示为 live（绿色）。
注意
Atlas 共享层级（M0/M2/M5）会阻止 getLog 管理命令，因此实时状态会读作 unavailable。请使用专用集群或自托管的副本集。
生成一个明显糟糕的扫描
在一个 shell 标签页中，对一个没有索引的字段运行一次慢速集合扫描——按一个无索引字段排序会强制对整个集合进行 COLLSCAN：
use <database>
db.<collection>.find({}).sort({ <unindexedField>: -1 }).limit(25).toArray()该查询耗时远超 100 ms，并扫描整个集合。
查看 New slow query 卡片
切回 Query Regressions 标签页并等待几秒（慢日志大约每 5 秒轮询一次）。
会出现一个标题为 New slow query — <namespace>（代码 Q7）的 WARN 卡片，执行计划为 COLLSCAN，且 docs examined 数值很高。
一个从未见过、却已经是大型 COLLSCAN 的查询会在首次出现时就被标记——无需 baseline。这是针对维护窗口期间落地的变更的防护。
证明指纹是稳定的（去重）
再运行完全相同的查询几次。
不会出现新卡片。 重复运行会折叠进同一条告警——相同指纹 = 相同身份。
这正是稳定指纹的全部意义所在：重新运行一个查询绝不会刷出重复告警。一个查询 = 一个身份，就像 sql_id。
证明不同形态会产生新告警
运行一个不同形态的 COLLSCAN——按一个不同的无索引字段排序：
use <database>
db.<collection>.find({}).sort({ <anotherUnindexedField>: -1 }).limit(25).toArray()会出现第二张、不同的卡片，带有不同的指纹。不同形态 = 新身份 = 新告警。
在 Cosmos DB 上进行实时采集（RU 模式）
Cosmos 没有可轮询的慢查询日志，因此采集会从 Azure Log Analytics 读取诊断日志。指标是 RU，而非毫秒。
在 Cloud Credentials 中接入 Log Analytics
在一个 Cosmos DB（Mongo API）连接上，打开 Cosmos Optimizer（Ctrl+Alt+Shift+O）→ Configuration → Cloud Credentials，并填写 Azure 区段：Cosmos 账户的 Resource ID 和 Log Analytics workspace ID。点击 Save。
会出现一条绿色确认信息（credentials saved … MetricsBridge promoted）。
注意
Log Analytics 是一个付费层级（写入 + 保留）。它是唯一能看到来自其他客户端的查询的路径——免费的 header 路径只能看到 NoSqlStudio 自己运行的内容，这对未声明变更的场景来说是不够的。
确认实时状态并生成一个昂贵的查询
在 Cosmos 连接上打开 Query Regressions；确认状态读作 live。然后运行一个跨分区或无索引的查询，使其消耗 RU。
在 Log Analytics 写入该行之后（有几分钟延迟），会出现一张卡片，以 RU 的前后值作为核心指标。
概念
在 Cosmos RU 模式下 Explain 不可用——弹窗会这样说明，并转而指引你查看 RU 指标和 Index Policy 面板。
在 DocumentDB 上进行实时采集
DocumentDB 不支持 getLog，因此采集会从 CloudWatch Logs 读取 DocDB profiler 流。它需要启用 profiler 并配置 AWS 凭据。
启用 DocDB profiler
在 AWS 中，创建一个自定义集群参数组，设置 profiler = enabled 和一个较低的 profiler_threshold_ms（例如 50），应用它（需要重启），并把 profiler 添加到集群的 Log exports to CloudWatch 中。
慢操作开始落入 CloudWatch 日志组 /aws/docdb/<cluster>/profiler。
在 Cloud Credentials 中设置 AWS 凭据
在 DocumentDB 连接上，打开 Cosmos Optimizer（Ctrl+Alt+Shift+O）→ Configuration → Cloud Credentials，并填写 AWS DocumentDB 区段：Region、DocDB cluster identifier，以及可选的 AWS profile（留空则使用机器的默认凭据链）。向下滚动并点击 Save credentials。
该区段会显示一个绿色的 CONFIGURED 徽章，并且 aws-documentdb MetricsBridge 会为此连接注册。
概念
此面板由 AWS DocumentDB 和 Azure Cosmos 共享，并且是按连接的——在 DocumentDB 连接上填写 AWS 区段，在 Cosmos 连接上填写 Azure 区段。每个连接携带各自的区域/集群，因此不同区域中的多个 DocDB 集群会被独立处理。
打开界面并生成一个慢扫描
在 DocumentDB 连接上打开 Query Regressions（确认状态为 live），然后在一个 shell 标签页中运行一次慢速 COLLSCAN：
use <database>
db.<collection>.find({}).sort({ <unindexedField>: -1 }).limit(25).toArray()在约 15 秒内会出现一张 New slow query 卡片，执行计划为 COLLSCAN，并带有一个推导出的 docs examined 数值。
注意
DocumentDB 不会直接发出 docsExamined，因此该值是从 profiler 的 execStats 扫描阶段推导出来的——对于无过滤的扫描是精确的，当某个阶段的过滤器排除了行时则是一个下界。一个高效的仅索引计数（IXONLYSCAN）即便有点慢，也会被有意地不标记——只有检查了大量文档的 COLLSCAN 才会被标记。
持久化与行为
状态在重新打开后依然保留
对一条告警执行 Acknowledge 或 snooze，然后关闭并重新打开 Query Regressions 标签页。
已确认/已暂停（snoozed）的状态以及你的范围选择都还在。
同一个界面，每种引擎
依次在 MongoDB、Cosmos 和 DocumentDB 连接上打开该界面。布局、卡片、五个 RCA 层级以及 AI 面板都完全相同——只有核心指标（ms 还是 RU）和 Explain 的可用性不同。
清理（完成之后）
删除你创建的任何一次性测试集合：
use <database>
db.<collection>.drop()对于 DocumentDB，如果 profiler 只是为了本次测试而启用，你可以在参数组中禁用它并删除 CloudWatch 日志组，以停止写入费用。对于 Cosmos，如果你不需要持续采集，请降低或禁用 Log Analytics 诊断设置。
测试数据已被清除，你为测试启用的任何付费云层级都已关停。
你所验证内容的总结
| 阶段 | 功能 |
|---|---|
| 1 | 无需数据库即可打开 Query Regressions 并加载演示数据 |
| 2 | 读懂一条告警：L1 指标、L2 执行计划差异、L3 结论、L4 附近事件、L5 AI、详情弹窗、修复措施 |
| 3 | 范围过滤器与范围外严重告警横幅（未声明变更防护） |
| 4 | MongoDB 实时采集：New slow query、稳定指纹去重、新形态 = 新告警 |
| 5 | 通过 Log Analytics 进行 Cosmos DB 实时采集，以 RU 作为指标 |
| 6 | 通过 CloudWatch profiler 流进行 DocumentDB 实时采集 |
| 7 | 状态/范围的持久化，以及在全部三种引擎上保持一致的同一个界面 |