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 は 0.3 秒ではなく 5 分です。デフォルトは 60 秒で、コールドキャッシュでは中程度の複雑さのクエリも気付かないうちに終了させてしまいます。