azure-kusto

Azure Data Explorer（Kusto / ADX）に溜めたログや計測データを引きたいときです。

ADX はログと計測データに特化した探索用のサービスで、数十億件に対して 1 秒未満で返すことを狙った作りです。引くための言語が KQL（Kusto Query Language）です。

このスキルがやることは 4 つ

1. 一覧するクラスタとデータベースを一覧する（テーブルの場所が分からなければ候補を全部探す）
2. スキーマを確認するテーブルのスキーマを確認する（データの形を掴む）
3. KQL で引くKQL で引く
4. 結果を読む結果を読む

段階 2 があるのが実用的です。列の名前と型を知らずに KQL を書かせると、それらしい列名を組み立てて空振りします。

テーブルの場所が分からないときは候補を全部探す

段階 1 には決まりが 1 つ付いています（2026-10-12 確認）。テーブルがどこにあるか分からず、候補のクラスタ・データベース・Log Analytics のワークスペースが複数あるときは、まとめて探し、全部の候補を確かめてから「見つからない」と報告せよ、という決まりです。

6 つの型が用意されている

用途ごとに KQL の骨格が示されています。

1. 素の取得

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

2. 集計

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

3. 時系列

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

4. 結合（相関）

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

5. スキーマの確認（kusto_table_schema_get）

6. 候補をまとめて探す（2026-10-12 確認）

候補を 1 つずつ照会するのではなく、読み取りだけのメタデータの探索をまとめて流します。各候補のテーブルを一覧し、テーブル名が完全に一致するものを見つけてからデータを引きます。見つかった先が複数なら、まとめて引く例があります。

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

3 番の型がそのまま使える

平均だけでなく 50 / 95 / 99 パーセンタイルを並べているのが良いところです。応答時間を平均だけで見ると、遅い一部が平均に埋もれます。

性能の指針が具体的

KQL は書き方で速さが大きく変わります。最善の実践の先頭に、性能のための指針がまとまっています（2026-10-12 確認）。

• 時間で早く絞る時間の範囲で早めに絞る
• 索引のある列から絞る索引のある列から絞る
• 結果を小さくする探索では take や limit で大きな結果を避ける
• 集計は向こうでsummarize で集計し、手元で集計しない

時間で早く絞るのが一番効きます。結果が空のときも、まず時間の範囲が狭すぎないかを見よ、と書かれています。

よく使う関数が列挙されている

• 時間ago(1h)、between(開始 .. 終了)、bin()
• 文字列startswith()、contains()、matches regex、parse、extract
• 集計percentiles()、avg()、sum()、max()、min()
• 列の操作project（必要な列だけ）、extend（計算列を足す）

KQL を書いたことがなくても始められるのが、このスキルの価値です。

運用の助言も入っている

引き方だけでなく、溜め方の助言もあります。

• よく使う照会はデータベースの関数として保存する
• 繰り返す集計にはマテリアライズドビューを使う
• データ保持のポリシーを当てて保管費用を抑える
• 1 秒未満の遅延が必要ならストリーミング取り込み

保持ポリシーの話が入っているのは実務的です。 ADX は溜め続けると費用が伸びます。

この公開元には組で入れないと止まるものがある

この公開元には組で入れないと止まるものがあります。全体の役割分担は microsoft/azure-skills の地図にまとめています。

ADX を使っていないなら関係ない

Log Analytics や Application Insights も KQL で引けますが、このスキルが想定しているのは ADX のクラスタです。Log Analytics のワークスペースは、6 番の型で「テーブルの探し先の候補」として出てくるだけです。監視系の調べ方そのものは azure-diagnostics の側に手順があります。

MCP サーバーが前提

本文が使う道具は kusto_cluster_list、kusto_database_list、kusto_query、kusto_table_schema_get の 4 つで、すべて MCP 経由です。

MCP が失敗したときの代わりとして、Azure CLI の手順が本文にあります。クラスタとデータベースの一覧・表示は az kusto、照会は az rest でクラスタの REST の口へ送る形です。60 秒を超えて時間切れになった、接続や認証に失敗した、データがあるはずなのに空、といった場合に切り替えます。

リレーショナルデータベースの設計には使えない

ADX は追記中心の探索用です。業務データの設計なら supabase-postgres-best-practices のような側になります。

データを入れる側の作業は扱っていない

取り込みの方式には触れていますが、本文の中心は引くことです。

解析で見つかったのはシェル実行とファイル書き換えの記述

SKILL.md の解析では、シェルコマンドを実行する記述とファイルを書き換える記述が見つかっています。同梱ファイルは 0 件です。

本番のデータを引く。ここが一番の注意点

引いた結果は会話に残ります。共有する前に中身を見てください。

サブスクリプションの指定が必要

本文が必須の引数として挙げています。ID か表示名のどちらかです。クラスタ名は .kusto.windows.net を付けずに渡す、と注意があります。

費用が発生する

ADX の照会は計算資源を使います。時間で絞らない照会は、費用と時間の両方を消費します。本文は時間で早く絞ることを性能のためと書き、照会の性能と資源の消費を見張るようにも勧めています。

take を付けずに探索させない

take を付けずに探索させないでください。本文も「探索的な照会には take か limit を使って大きな結果を避けよ」と書いています。エージェントに任せると、件数を気にせず引くことがあります。

取り込んだばかりのデータは遅れて見える

ストリーミングのデータは、取り込みの方式によって 1〜30 秒遅れることがある、と本文にあります。

結果の解釈は人が判断する

「エラーが 50 件」は事実ですが、「だから原因はここ」は別の話です。

KQL を知らなくても使えますか

使えます。6 つの型が用意されていて、テーブル名と列名を差し替えれば動く形になっています。

ただし段階 2（スキーマの確認）を飛ばさないでください。列の名前と型を確認してから書かないと、空振りします。

応答時間の分析はどう書けばいいですか

本文の 3 番の型がそのまま使えます。

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

平均だけを見ないでください。 95 と 99 パーセンタイルを並べると、遅い一部が見えます。bin(Timestamp, 5m) の幅は見たい粒度に合わせて変えてください。

照会が遅いときはどうすればいいですか

本文の性能の指針を当ててください。最初に見るのは時間の絞り込みです。

1. 時間の絞り込みが早くにあるか
2. 索引のある列から絞っているか
3. take や limit で件数を抑えているか
4. 集計を summarize で済ませているか

繰り返す集計なら、マテリアライズドビューに寄せる案も本文に挙がっています。

Log Analytics でも同じ KQL が使えますか

言語は同じですが、テーブルの構成が違います。このスキルが想定しているのは ADX のクラスタです。テーブルの場所が分からないときの探し先として Log Analytics のワークスペースも挙がり、workspace('ws1') のように複数のワークスペースをまとめて引く例が 6 番の型にあります。

Azure の監視系（Log Analytics、Application Insights）を引くなら azure-diagnostics の手順のほうが噛み合います。あちらには診断用の KQL の定型が別ファイルであります。

MCP サーバーを使わずに引けますか

引けます。中心の 4 つの道具は MCP 経由ですが、MCP が使えないときの代わりとして Azure CLI の手順が本文にあります。照会は az rest でクラスタの REST の口（/v1/rest/query）に KQL を送る形です。

Azure の MCP に対する態度は、同じ公開元の中でも分かれています。azure-diagnostics は AppLens（MCP）を勧め、azure-quotas は azure-quota の MCP を「絶対に使うな」と書いています。機能ごとに判断してください。

対応しているエージェントはどれですか

Claude Code と Codex です。公開元の README が Claude Code と Codex CLI それぞれへの入れ方を節に分けて案内しています（2026-10-09 確認）。当サイトは公開元が明記しているものだけを「対応」として表示する方針なので、このスキルのページには両方が対応として出ます（指標の意味と限界）。