azure-kusto

Azure Data Explorer（Kusto）のクエリと分析

ログ、テレメトリ、時系列データに対する高速でスケーラブルなビッグデータ分析のために、KQL クエリを実行し、Azure Data Explorer リソースを管理します。

概要

このスキルを使うと、ログおよびテレメトリデータに最適化された、高速で拡張性の高いデータ探索サービスである Azure Data Explorer（Kusto）に対して、クエリと管理を実行できます。Azure Data Explorer は、Kusto Query Language（KQL）を使用して、数十億件のレコードを1秒未満でクエリできます。

主な機能：

• クエリ実行：大規模なデータセットに対して KQL クエリを実行します
• スキーマの探索：テーブル、列、データ型を確認します
• リソース管理：クラスターとデータベースを一覧表示します
• 分析：集計、時系列、異常検出、機械学習

基本的なワークフロー

1. リソースを確認する：サブスクリプション内で利用可能なクラスターとデータベースを一覧表示します。対象テーブルの場所が不明で、候補となるクラスター、データベース、または Log Analytics ワークスペースが複数ある場合は、検索をまとめて実行し（パターン6を参照）、すべての候補を確認してから「見つからない」と報告してください。
2. スキーマを確認する：テーブル構造を取得して、データモデルを把握します
3. データをクエリする：分析、フィルタリング、集計のために KQL クエリを実行します
4. 結果を分析する：クエリ出力から分析情報を抽出し、レポートを作成します

クエリパターン

パターン1：基本的なデータ取得

簡単なフィルタリングで、テーブルから最近のレコードを取得します。

KQL の例：

Events
| where Timestamp > ago(1h)
| take 100

用途：データの簡易確認、最近のイベントの取得

パターン2：集計分析

分析やレポート作成のために、ディメンションごとにデータを集計します。

KQL の例：

Events
| summarize count() by EventType, bin(Timestamp, 1h)
| order by count_ desc

用途：イベント数のカウント、分布分析、上位N件のクエリ

パターン3：時系列分析

傾向やパターンを把握するために、時間枠ごとにデータを分析します。

KQL の例：

Telemetry
| where Timestamp > ago(24h)
| summarize avg(ResponseTime), percentiles(ResponseTime, 50, 95, 99) by bin(Timestamp, 5m)
| render timechart

用途：パフォーマンス監視、傾向分析、異常検出

パターン4：結合と相関分析

複数のテーブルを結合して、データセットを横断的に分析します。

KQL の例：

Events
| where EventType == "Error"
| join kind=inner (
    Logs
    | where Severity == "Critical"
) on CorrelationId
| project Timestamp, EventType, LogMessage, Severity

用途：根本原因分析、相関するイベントの追跡

パターン5：スキーマの確認

クエリを実行する前に、テーブル構造を確認します。

ツール：kusto_table_schema_get

用途：データモデルの把握、クエリの計画

パターン6：候補ソースを横断した一括検索

テーブルの場所が不明で、候補となるクラスター、データベース、またはワークスペースが複数ある場合は、候補を一つずつクエリするのではなく、読み取り専用のメタデータ探索をまとめて実行します。各候補データベースまたはワークスペース内のテーブルを一覧表示し、データをクエリする前にテーブル名が完全一致するものを探します。

テーブルを含むソースを確認したら、必要に応じてそれらのソースをまとめてクエリします：

union workspace('ws1').Requests, workspace('ws2').Requests
| take 1

用途：複数の候補リソースの中からテーブルを特定し、空の結果をテーブルが存在しないことと混同しないようにします

主なデータフィールド

クエリを実行する際によく使われるフィールドパターン：

• Timestamp：イベントの時刻（datetime）— 時間のフィルタリングには ago()、between()、bin() を使用します
• EventType/Category：グループ化に使う分類フィールド
• CorrelationId/SessionId：関連イベントの追跡に使用します
• Severity/Level：重要度によるフィルタリングに使用します
• Dimensions：グループ化やフィルタリングに使うカスタムプロパティ

結果の形式

クエリ結果には次の情報が含まれます：

• 列：フィールド名とデータ型
• 行：クエリに一致するデータレコード
• 統計情報：行数、実行時間、リソース使用状況
• 可視化：グラフ描画のヒント（timechart、barchart など）

KQL のベストプラクティス

🔵 クエリパターン：

• 集計では count() だけを使うのではなく、summarize を使用します
• 時系列データの時間区間分割には bin() を使用します
• 必要な列だけを選択するには project を使用します
• 計算フィールドを追加するには extend を使用します

🟡 よく使われる関数：

• ago(timespan)：相対時間（ago(1h)、ago(7d)）
• between(start .. end)：範囲によるフィルタリング
• startswith()、contains()、matches regex：文字列のフィルタリング
• parse、extract：文字列から値を抽出します
• percentiles()、avg()、sum()、max()、min()：集計

ベストプラクティス

• 時間範囲フィルターで早い段階から絞り込んでクエリのパフォーマンスを最適化し、まずインデックス付きの列を使用します
• 探索的なクエリでは take または limit を使用して、大量の結果が返されるのを防ぎます
• クライアント側で処理する代わりに、集計には summarize を活用します
• 頻繁に使用するクエリは、データベース内の関数として保存します
• 繰り返し行う集計には、マテリアライズドビューを使用します
• クエリのパフォーマンスとリソース消費を監視します
• ストレージコストを管理するため、データ保持ポリシーを適用します
• リアルタイム分析（レイテンシー 1 秒未満）には、ストリーミング取り込みを使用します
• 運用状況を把握するため、Azure Monitor と統合します

使用する MCP ツール

ツール	目的
kusto_cluster_list	サブスクリプション内のすべての Azure Data Explorer クラスターを一覧表示します
kusto_database_list	指定した Kusto クラスター内のすべてのデータベースを一覧表示します
kusto_query	Kusto データベースに対して KQL クエリを実行します
kusto_table_schema_get	指定したテーブルのスキーマ情報を取得します

必須パラメーター：

• subscription：Azure サブスクリプション ID または表示名
• cluster：Kusto クラスター名（例：「mycluster」）
• database：データベース名
• query：KQL クエリ文字列（クエリ操作の場合）
• table：テーブル名（スキーマ操作の場合）

任意のパラメーター：

• resource-group：リソースグループ名（一覧表示操作の場合）
• tenant：Azure AD テナント ID

フォールバック戦略：Azure CLI コマンド

Azure MCP Kusto ツールが失敗する、タイムアウトする、または利用できない場合は、フォールバックとして Azure CLI コマンドを使用します。

CLI コマンドリファレンス

操作	Azure CLI コマンド
クラスターの一覧表示	az kusto cluster list --resource-group <rg-name>
データベースの一覧表示	az kusto database list --cluster-name <cluster> --resource-group <rg-name>
クラスターの表示	az kusto cluster show --name <cluster> --resource-group <rg-name>
データベースの表示	az kusto database show --cluster-name <cluster> --database-name <db> --resource-group <rg-name>

Azure CLI による KQL クエリ

クエリには、Kusto REST API またはクラスターの直接 URL を使用します：

az rest --method post \
  --url "https://<cluster>.<region>.kusto.windows.net/v1/rest/query" \
  --body "{ \"db\": \"<database>\", \"csl\": \"<kql-query>\" }"

フォールバックするタイミング

次の場合は Azure CLI に切り替えます：

• MCP ツールがタイムアウトエラーを返す場合（クエリが 60 秒を超える場合）
• MCP ツールが「service unavailable」または接続エラーを返す場合
• MCP ツールで認証に失敗する場合
• データベースにデータがあると分かっているのに、空の応答が返る場合

よくある問題

• アクセス拒否：データベースのアクセス許可を確認します（クエリには最低でも Viewer ロールが必要です）
• クエリのタイムアウト：時間フィルターでクエリを最適化し、結果セットを小さくするか、タイムアウトを延長します
• 構文エラー：KQL の構文を検証します。よくある問題：パイプの欠落、演算子の誤り
• 結果が空：時間範囲フィルターを確認し（絞り込みすぎている可能性があります）、テーブル名を検証します
• テーブルの場所が不明：データが存在しないと結論付ける前に、パターン 6 を使用して候補となるすべてのソースをまとめて検索します
• クラスターが見つからない：クラスター名の形式を確認します（「.kusto.windows.net」サフィックスは除きます）
• CPU 使用率が高い：クエリの範囲が広すぎます。フィルターを追加し、時間範囲を短縮するか、集計を制限します
• 取り込みの遅延：取り込み方法によっては、ストリーミングデータに 1～30 秒の遅延が生じることがあります

ユースケース

• ログ分析：アプリケーションログ、システムログ、監査ログ
• IoT 分析：センサーデータ、デバイスのテレメトリ、リアルタイム監視
• セキュリティ分析：SIEM データ、脅威検出、セキュリティイベントの相関分析
• APM：アプリケーションのパフォーマンス指標、ユーザーの行動、エラー追跡
• ビジネスインテリジェンス：クリックストリーム分析、ユーザー分析、運用 KPI