erikdarlingdata/PerformanceStudio

# Performance Studio

一款跨平台的 SQL Server 执行计划分析工具，内置用于 AI 辅助分析的 MCP 服务器。它可以解析 `.sqlplan` XML，识别性能问题，建议缺失的索引，并提供可操作的警告——既可以通过命令行使用，也可以通过桌面 GUI 使用。 专为希望在不点击 SSMS 的情况下获得快速、自动化计划分析的开发人员和 DBA 而构建。 ## 截图 ### 查询编辑器 使用语法高亮和 SQL 关键字补全编写查询，连接到任何 SQL Server，并一键捕获计划。  ### 带有计划洞察的实际执行计划 图形化计划树，具有 SSMS 风格的操作符图标、成本百分比、行数和警告徽章。计划洞察面板一目了然地显示运行时摘要、缺失索引、参数和等待统计信息。  ### 多语句导航 导航包含多个语句的存储过程和批处理。单击网格中的任何语句以跳转到其计划。计划洞察显示带有编译值与运行时值的参数。  ### 操作符工具提示和属性 将鼠标悬停在任何操作符上，即可查看包含成本、行数、I/O、时间、并行度和警告的详细工具提示。单击以打开完整的属性面板，其中包含每线程时间、谓词等更多信息。   ### 给人类的建议 一键式文本报告，包含服务器上下文、警告、等待统计信息和昂贵的操作符——可供阅读或分享。  ### 计划比较 并排比较两个计划，显示成本、运行时、I/O、内存和等待统计信息的差异。  ### Query Store 集成 从 Query Store 获取按 CPU、持续时间、逻辑读取、物理读取、写入、内存或执行次数排名靠前的查询，并将其计划直接加载到分析器中。  ### MCP 集成 让 Claude Code 分析加载的计划、识别警告、建议索引并比较计划——所有这些都通过内置的 MCP 服务器完成。  ## 功能 向它提供一个查询计划，它会告诉你哪里出了问题： - **大型内存授予** — 标记出囤积了未使用内存的查询 - **行估计偏差** — 查找估计值与实际值相差 10 倍以上的操作符 - **缺失索引** — 提取 SQL Server 的索引建议，并提供可立即运行的 CREATE 语句 - **Hash、排序和交换溢出** — 识别将数据溢出到 TempDB 的操作符，并根据数据量确定严重程度 - **并行倾斜** — 检测某些线程在做所有工作而其他线程处于空闲状态的情况 - **扫描谓词** — 当扫描使用残留谓词过滤行时发出警告 - **键和 RID 查找** — 标记回查基表的操作，区分堆和聚集索引 - **延迟过滤** — 查找在计划深处丢弃行的 Filter 操作符 - **嵌套循环问题** — 标记执行次数过高的嵌套循环，这些循环可能更适合作为哈希连接 - **参数嗅探** — 比较编译值与运行时参数值 - **标量 UDF** — 警告执行路径中的 T-SQL 和 CLR 标量函数 - **隐式转换** — 检测类型不匹配，当阻止查找计划时提高严重程度 - **反模式** — OPTIMIZE FOR UNKNOWN、包含可空列的 NOT IN、前导通配符、函数包装的谓词等 每个警告都包含严重程度（信息、警告或严重）、操作符节点 ID 以及足够立即采取行动的上下文。 ## 前置条件 - [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)（构建和运行所必需） - SQL Server 实例（可选——仅实时计划捕获需要；文件分析无需实例） - Docker（可选——macOS/Linux 用户可以通过 Docker 在本地运行 SQL Server） ## 下载 预构建的二进制文件可在 [Releases](https://github.com/erikdarlingdata/PerformanceStudio/releases/latest) 页面获取： | Platform | Download | |----------|----------| | Windows (x64) | [PerformanceStudio-win-x64.zip](https://github.com/erikdarlingdata/PerformanceStudio/releases/latest/download/PerformanceStudio-win-x64.zip) | | macOS (Apple Silicon) | [PerformanceStudio-osx-arm64.zip](https://github.com/erikdarlingdata/PerformanceStudio/releases/latest/download/PerformanceStudio-osx-arm64.zip) | | macOS (Intel) | [PerformanceStudio-osx-x64.zip](https://github.com/erikdarlingdata/PerformanceStudio/releases/latest/download/PerformanceStudio-osx-x64.zip) | | Linux (x64) | [PerformanceStudio-linux-x64.zip](https://github.com/erikdarlingdata/PerformanceStudio/releases/latest/download/PerformanceStudio-linux-x64.zip) | 这些是自包含的——不需要 .NET SDK。解压 zip 文件并运行即可。 **macOS 注意：** macOS 可能会阻止该应用，因为它未使用 Apple 开发者证书签名。如果您看到应用“无法打开”的警告，请在解压后运行以下命令： ``` xattr -cr PerformanceStudio.app ``` 然后正常打开应用。 ## 从源代码构建 克隆并构建： ``` git clone https://github.com/erikdarlingdata/PerformanceStudio.git cd PerformanceStudio dotnet build ``` 要验证构建： ``` dotnet test tests/PlanViewer.Core.Tests # 37 tests should pass dotnet run --project src/PlanViewer.Cli -- analyze --help ``` ## 快速开始 ### 分析现有的 .sqlplan 文件 如果您已经有一个 `.sqlplan` 文件（从 SSMS、Azure Data Studio 或其他工具保存）： ``` # JSON 输出（默认）— 完整的 operator tree，适合自动化 planview analyze my_query.sqlplan # 人类可读的文本输出 planview analyze my_query.sqlplan --output text # 文本输出，仅包含警告和缺失的索引（跳过 operator tree） planview analyze my_query.sqlplan --output text --warnings-only ``` ### 从实时服务器捕获并分析计划 连接到 SQL Server 实例，运行查询，并自动捕获其执行计划。 **最快的方式** — 直接传递凭据： ``` # 捕获实际的执行计划（查询 WILL 运行） planview analyze --server sql2022 --database AdventureWorks \ --login sa --password YourPassword \ --query "SELECT * FROM Sales.SalesOrderHeader WHERE OrderDate > '2024-01-01'" \ --trust-cert --output-dir ./results/ # 捕获估算的计划（对生产环境安全 — 查询 NOT 执行） planview analyze --server sql2022 --database AdventureWorks \ --login sa --password YourPassword \ --query "SELECT * FROM Sales.SalesOrderHeader" \ --estimated --trust-cert --output-dir ./results/ ``` **使用 .env 文件** — 在您的工作目录中放置一个 `.env` 文件，以避免重复输入连接详细信息： ``` # .env PLANVIEW_SERVER=sql2022 PLANVIEW_DATABASE=AdventureWorks PLANVIEW_LOGIN=sa PLANVIEW_PASSWORD=YourPassword PLANVIEW_TRUST_CERT=true ``` 然后只需运行： ``` planview analyze --query "SELECT * FROM Sales.SalesOrderHeader" planview analyze ./queries/ --output-dir ./results/ ``` 当同时提供时，CLI 参数会覆盖 `.env` 值。 **使用凭据存储** — 为了长期使用，将凭据存储在您的 OS 密钥链中： ``` # 存储凭据（每个服务器一次） planview credential add sql2022 --user sa # 系统将提示您输入密码 — 它存储在您的 OS credential store 中 # 现在无需 --login/--password 即可连接 planview analyze --server sql2022 --database AdventureWorks \ --query "SELECT * FROM Sales.SalesOrderHeader" \ --trust-cert --output-dir ./results/ ``` **批量处理** 一个 .sql 文件文件夹： ``` planview analyze ./queries/ --server sql2022 --database StackOverflow2013 \ --login sa --password YourPassword \ --trust-cert --output-dir ./results/ ``` 批处理模式为每个查询生成三个文件： - `query_name.sqlplan` — 原始执行计划 XML（可在 SSMS 或 Performance Studio GUI 中打开） - `query_name.analysis.json` — 结构化分析，包含警告、缺失索引和操作符树 - `query_name.analysis.txt` — 人类可读的文本报告 ### 管理凭据 ``` planview credential add my-server --user sa # prompts for password planview credential add my-server --user sa -p pwd # non-interactive planview credential list # show stored credentials planview credential remove my-server # delete credential ``` 凭据存储在 OS 凭据存储中——Windows 上为 Windows Credential Manager，macOS 上为 Apple Keychain。没有任何内容以明文形式写入磁盘。 ## 示例输出 这些示例是针对 SQL Server 2022 上的 StackOverflow2013 生成的。源查询位于 [`examples/queries/`](examples/queries/)，计划和分析位于 [`examples/output/`](examples/output/)。 ### 文本输出 (`--output text`) ``` Plan: 04_comment_heavy_posts.sqlplan SQL Server: 1.564 (build 16.0.4222.2) Statements: 1 --- Statement 1: SELECT --- Query: SELECT p.Id, p.Title, p.Score, COUNT(c.Id) AS CommentCount FROM dbo.Posts AS p JOIN dbo.Comments AS c ON c.PostId = p.Id WHERE p.PostTypeId = 1 GROUP BY p.Id, p.Title, p.Score HAVING COUNT(c.Id) > 20 ORDER BY CommentCount DESC Estimated cost: 4069.8700 DOP: 8 Runtime: 4551ms elapsed, 15049ms CPU Memory grant: 8,022,664 KB granted, 2,514,944 KB used Warnings: [Critical] Large Memory Grant: Query granted 7835 MB of memory. Operator warnings: [Critical] Parallelism (Node 0): Estimated 1 rows, actual 2,889 (2889x underestimated). [Critical] Sort (Node 1): Estimated 1 rows, actual 2,889 (2889x underestimated). [Warning] Sort (Node 1): Thread 1 processed 100% of rows. Work is heavily skewed. [Warning] Filter (Node 2): Filter discards rows late in the plan. Missing indexes: StackOverflow2013.dbo.Posts (impact: 74%) CREATE NONCLUSTERED INDEX [IX_Posts_PostTypeId] ON dbo.Posts (PostTypeId) INCLUDE (Score, Title) StackOverflow2013.dbo.Comments (impact: 19%) CREATE NONCLUSTERED INDEX [IX_Comments_PostId] ON dbo.Comments (PostId) === Summary === Warnings: 8 (4 critical) Missing indexes: 2 Actual stats: yes Warning types: Filter Operator, Large Memory Grant, Parallel Skew, Row Estimate Mismatch, Scan With Predicate ``` ### JSON 输出（默认） 默认的 JSON 输出包含完整的操作符树，使其适用于 CI 流水线、LLM 消费或进一步处理。有关完整示例，请参阅 [`examples/output/`](examples/output/)。 ### 批量处理 ``` $ planview analyze ./examples/queries/ --server sql2022 \ --database StackOverflow2013 --trust-cert --output-dir ./results/ Capturing actual plans from sql2022/StackOverflow2013 [1/5] 01_top_users_by_posts ... OK (1.8s) [2/5] 02_recent_questions ... OK (0.8s) [3/5] 03_unanswered_high_score ... OK (0.7s) [4/5] 04_comment_heavy_posts ... OK (4.7s) [5/5] 05_user_vote_summary ... OK (4.3s) Processed 5 files: 5 succeeded, 0 failed Output: ./results/ ``` ## 桌面 GUI 基于 Avalonia 的 GUI 以可视化方式呈现执行计划，使用与 SSMS 相同的操作符图标。通过文件 > 打开或拖放来打开 `.sqlplan` 文件。 功能： - 带有成本百分比和行数的图形化计划树 - 根节点上的警告徽章，显示警告总数 - 计划洞察面板 — 三列视图，包含运行时摘要、缺失索引和等待统计信息可视化 - 缩放和平移（鼠标滚轮 + 中键拖动） - 单击任何操作符以查看完整属性（30 个部分） - 语句网格，具有可排序的列（成本、行数、DOP、警告） - 悬停时显示关键操作符指标的工具提示 - **给人类的建议** — 一键式文本分析报告，可供阅读或分享 - **给机器的建议** — 一键式 JSON 导出，专为 LLM 和自动化设计 - **计划比较** — 并排比较两个计划（成本、运行时、I/O、内存、等待统计信息） - **复制复现脚本** — 将参数、SET 选项和查询文本提取到可运行的 `sp_executesql` 脚本中 - **获取实际计划** — 连接到服务器并重新执行查询以捕获运行时统计信息 - **Query Store 分析** — 连接到服务器并按 CPU、持续时间或读取次数分析排名靠前的查询 - **MCP 服务器** — 内置的 Model Context Protocol 服务器，用于 AI 辅助计划分析（可选） - 深色主题 ``` dotnet run --project src/PlanViewer.App ``` ## SSMS 扩展 一个 VSIX 扩展，用于在 SSMS 18-22 的执行计划右键上下文菜单中添加 **"Open in Performance Studio"**。 ### 工作原理 1. 在 SSMS 中右键单击任何执行计划 2. 单击 "Open in Performance Studio" 3. 扩展通过反射提取计划 XML 并将其保存到临时文件 4. Performance Studio 打开并加载该计划 ### 安装 1. 从 [v0.7.0 release](https://github.com/erikdarlingdata/PerformanceStudio/releases/tag/v0.7.0) 下载 `PlanViewer.Ssms.vsix` 和 `InstallSsmsExtension.exe`（SSMS 扩展尚未包含在自动构建中） 2. 将它们放在同一文件夹中 3. 双击 `InstallSsmsExtension.exe` 并批准 UAC 提示 4. 安装程序会自动检测 SSMS 21 和/或 SSMS 22 并安装到两者中 5. 重启 SSMS 以激活扩展 ### 首次运行 首次使用时，如果未自动找到 Performance Studio，扩展将提示您定位 `PlanViewer.App.exe`。路径会保存到注册表（`HKCU\SOFTWARE\DarlingData\SQLPerformanceStudio\InstallPath`），因此您只需执行一次此操作。 扩展按以下顺序搜索应用： 1. 注册表项（首次浏览后自动设置） 2. 系统 PATH 3. 常见安装位置（`%LOCALAPPDATA%\Programs\SQLPerformanceStudio\`、`Program Files` 等） ## MCP 服务器 (LLM 集成) 桌面 GUI 包含一个嵌入式 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，向 Claude Code 和 Cursor 等 LLM 客户端公开已加载的执行计划和 Query Store 数据。 ### 设置 1. 在 `~/.planview/settings.json` 中启用 MCP 服务器： ``` { "mcp_enabled": true, "mcp_port": 5152 } ``` 2. 向 Claude Code 注册： ``` claude mcp add --transport http --scope user performance-studio http://localhost:5152/ ``` 3. 打开一个新的 Claude Code 会话并询问如下问题： - "应用程序中加载了哪些计划？" - "分析执行计划并告诉我哪里出了问题" - "是否有任何缺失索引建议？" - "比较这两个计划——哪个更好？" - "从 Query Store 获取按 CPU 排名的前 10 个查询" ### 可用工具 13 个用于计划分析和 Query Store 数据的工具： | Category | Tools | |---|---| | Discovery | `list_plans`, `get_connections` | | Plan Analysis | `analyze_plan`, `get_plan_summary`, `get_plan_warnings`, `get_missing_indexes`, `get_plan_parameters`, `get_expensive_operators`, `get_plan_xml`, `compare_plans`, `get_repro_script` | | Query Store | `check_query_store`, `get_query_store_top` | 计划分析工具适用于应用中加载的计划（通过文件打开、粘贴、查询执行或 Query Store 获取）。Query Store 工具使用内置的只读 DMV 查询——无法执行任意 SQL。 MCP 服务器仅绑定到 `localhost`，不接受远程连接。默认情况下禁用。 ## 项目结构 ``` PerformanceStudio/ ├── src/ │ ├── PlanViewer.Core/ # Analysis engine (parser, 30 rules, layout) │ ├── PlanViewer.App/ # Avalonia desktop GUI │ ├── PlanViewer.Cli/ # CLI tool (planview command) │ ├── PlanViewer.Ssms/ # SSMS extension (.vsix, .NET Framework 4.7.2) │ └── PlanViewer.Ssms.Installer/ # SSMS extension installer (auto-detects SSMS 21/22) ├── tests/ │ └── PlanViewer.Core.Tests/ # 37 xUnit tests with real .sqlplan fixtures ├── examples/ │ ├── plans/ # Sample .sqlplan files for testing │ ├── queries/ # Sample .sql files │ └── output/ # Generated .sqlplan, .analysis.json, .txt └── PlanViewer.sln ``` ## CLI 参考 ### `planview analyze` ``` Usage: planview analyze [] [options] Arguments: .sqlplan file, .sql file, or directory of .sql files Options: --stdin Read plan XML from stdin -o, --output json (default) or text --compact Compact JSON (no indentation) --warnings-only Skip operator tree, only output warnings and indexes -s, --server SQL Server name (matches credential store key) -d, --database Database context for execution -q, --query Inline SQL text to execute --output-dir Directory for output files --estimated Estimated plan only (query is NOT executed) --auth windows, sql, or entra (default: auto-detect) --trust-cert Trust server certificate --timeout Query timeout (default: 60) --login SQL Server login (bypasses credential store) --password SQL Server password (bypasses credential store) ``` ### `planview credential` ``` planview credential add --user [-p ] planview credential list planview credential remove ``` ## 身份验证 有三种身份验证方式，按优先级排列： 1. **`--login` / `--password`** — 直接在命令行上传递（或通过 `.env` 文件）。最适用于开发/测试。 2. **凭据存储** — 通过 `planview credential add` 存储在 Windows Credential Manager 或 Apple Keychain 中。最适合重复使用。 3. **Windows 身份验证** — 当未找到 SQL 凭据时自动使用。需要有效的 Kerberos 票据。 使用 `--auth windows`、`--auth sql` 或 `--auth entra` 覆盖自动检测。 **macOS 注意：** Windows 身份验证在 macOS 上不起作用（默认没有 Kerberos 票据）。请改用 `--login`/`--password`、凭据存储或 `--auth entra`。 ## 平台支持 | Platform | | CLI | Credential Store | |----------|-----|-----|-----------------| | Windows | Yes | Yes | Windows Credential Manager | | macOS | Yes | Yes | Apple Keychain | | Linux | Yes | Yes | Not yet (file analysis works) | ### macOS：通过 Docker 使用 SQL Server macOS 用户需要一个 SQL Server 实例来使用实时捕获功能。最简单的方法是使用 Docker： ``` docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=YourPassword123" \ -p 1433:1433 --name sql_server \ -d mcr.microsoft.com/mssql/server:2022-latest # 存储凭据 planview credential add localhost --user sa -p YourPassword123 # 测试连接性 planview analyze --server localhost --database master --trust-cert \ --query "SELECT @@VERSION" -o text ``` 对于本地 Docker 实例，请始终使用 `--trust-cert`。 ## 分析规则 分析器对每个计划运行 30 条规则，涵盖： | Category | Rules | |----------|-------| | Memory | Large grants, grant vs used ratio, spills to TempDB (including exchange spills) | | Estimates | Row estimate mismatches (10x+), zero-row actuals, row goals | | Indexes | Missing index suggestions, key lookups, RID lookups, scan with residual predicates | | Parallelism | Serial plan reasons, thread skew, ineffective parallelism, DOP reporting | | Joins | Nested loop high executions, many-to-many merge join worktables | | Filters | Late filter operators with impact quantification, function-wrapped predicates | | Functions | Scalar UDF detection (T-SQL and CLR), UDF timing | | Parameters | Compiled vs runtime values, sniffing issue detection | | Patterns | Leading wildcards, implicit conversions (with seek plan severity upgrade), OPTIMIZE FOR UNKNOWN, NOT IN with nullable columns, OR expansion, CASE in predicates | | Compilation | High compile CPU, compile memory exceeded, early abort | | Objects | Table variables, table-valued functions, CTE multiple references, eager index spools, lazy spools, row count spools | | Operators | Operator self-time calculation with per-thread awareness for parallel plans | 可以通过 `.planview.json` 配置文件禁用规则或覆盖其严重程度。请参阅 `--config` 选项。 ## 赞助商

Free code signing on Windows provided by SignPath.io, certificate by SignPath Foundation

## 许可证 MIT — 请参阅 [LICENSE](LICENSE)。 执行计划操作符图标来自 Microsoft 的 [vscode-mssql](https://github.com/microsoft/vscode-mssql) 扩展 (MIT)。详情请参阅 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

标签：AI 辅助, CLI, GUI, MCP 服务器, SOC Prime, SQL Server, SQL 审计, SSMS, WiFi技术, 代码审查, 代码示例, 开发工具, 开源, 性能优化, 执行计划, 扩展, 插件, 数据分析, 数据库性能分析, 数据库管理, 数据库调优, 检测绕过, 缺失索引检测