power-bi-diagnostics

Power BI 诊断技能

排查性能问题、跟踪查询并验证 pbi-cli 环境。

前提条件

pipx install pbi-cli-tool
pbi-cli skills install
pbi connect

环境检查

# Verify pythonnet and .NET DLLs are installed
pbi setup

# Show detailed environment info (version, DLL paths, pythonnet status)
pbi setup --info
pbi --json setup --info

# Check CLI version
pbi --version

快速故障排查

如果 pbi-cli 无法正常工作，请按顺序运行以下检查：

# 1. Is pbi-cli installed correctly?
pbi --version
pbi setup --info

# 2. Is Power BI Desktop running with a model open?
pbi connect

# 3. Is the connection still alive?
pbi connections last

# 4. Can you query the model?
pbi dax execute "EVALUATE ROW(\"test\", 1)"

模型健康检查

# Quick model overview
pbi --json model get

# Object counts (tables, columns, measures, relationships, partitions)
pbi --json model stats

# List all tables with column/measure counts
pbi --json table list

查询跟踪

在执行 DAX 查询期间捕获诊断事件：

# Start a trace
pbi trace start

# Execute the query you want to profile
pbi dax execute "EVALUATE SUMMARIZECOLUMNS(Products[Category], \"Total\", SUM(Sales[Amount]))"

# Stop the trace
pbi trace stop

# Fetch captured trace events
pbi --json trace fetch

# Export trace events to a file
pbi trace export ./trace-output.json

缓存管理

# Clear the formula engine cache (do this before benchmarking)
pbi dax clear-cache

连接诊断

# List all saved connections
pbi connections list
pbi --json connections list

# Show the last-used connection
pbi connections last

# Reconnect to a specific data source
pbi connect -d localhost:54321

# Disconnect
pbi disconnect

工作流：分析慢速查询

# 1. Clear cache for a clean benchmark
pbi dax clear-cache

# 2. Start tracing
pbi trace start

# 3. Run the slow query
pbi dax execute "EVALUATE SUMMARIZECOLUMNS(Products[Category], \"Total\", SUM(Sales[Amount]))" --timeout 300

# 4. Stop tracing
pbi trace stop

# 5. Export trace for analysis
pbi trace export ./slow-query-trace.json

# 6. Review trace events
pbi --json trace fetch

工作流：模型健康审计

# 1. Model overview
pbi --json model get
pbi --json model stats

# 2. Check table sizes and structure
pbi --json table list

# 3. Review relationships
pbi --json relationship list

# 4. Check security roles
pbi --json security-role list

# 5. Export full model for offline review
pbi database export-tmdl ./audit-export/

最佳实践

• 基准测试前清除缓存：pbi dax clear-cache
• 对长时间运行的查询使用 --timeout，避免过早取消
• 将跟踪导出到文件，以便与团队成员共享
• 排查环境问题时，先运行 pbi setup --info
• 使用 --json 输出编写自动化监控脚本
• 使用 pbi repl 通过持久连接进行交互式调试

---

注意事项

• 即使连接到过期端口，pbi connect 也会成功： Desktop 每次重启时都会重新分配其本地 Analysis Services 端口。来自上一会话的连接可能会绑定到当前被其他模型占用的端口，导致查询返回错误文件中的数据。重启 Desktop 后，务必重新运行 pbi connect，不要重复使用已保存的连接。
• pbi setup --info 报告的是 pythonnet 状态，而非运行时健康状况： pythonnet: ok 绿色提示表示 DLL 已加载，但并不能验证 AdomdClient 是否能与模型通信。在确认环境正常之前，请先用 EVALUATE ROW("test", 1) 之类的轻量查询进行验证。
• 跟踪事件会异步到达： 在 trace stop 后立即运行 pbi trace fetch 可能会返回空列表。请等待 1-2 秒，或通过短暂的重试循环调用 fetch；事件会先缓存在 AS 服务端，然后才刷新。
• 清除公式引擎缓存不会清除存储引擎缓存： clear-cache 后再次运行基准查询，仍会命中缓存的 VertiPaq 段。如需真正的冷启动基准测试，请重启 Desktop 或重新连接。
• model stats 也会统计隐藏对象： 计算组、自动日期层次结构和翻译表会增加表数量，使其高于用户在字段列表中看到的数量。请使用按可见性筛选的 table list 进行交叉核对。
• --timeout 的单位是秒，而不是毫秒： 很容易弄错——--timeout 300 表示 5 分钟，而不是 0.3 秒。默认值为 60 秒，在冷缓存下，任何复杂度中等的查询都可能被静默终止。