mcpField
A
azure-kusto

azure-kusto

官方
github.com/microsoft数据与数据库1.6k568.8k 次安装今天更新
代码仓库

关于 azure-kusto

Azure Data Explorer（Kusto）查询与分析 Skill，用于执行 KQL 查询并管理 Azure Data Explorer 资源。适合需要分析日志、遥测和时间序列数据的团队。

主要功能

  1. 01执行 KQL 查询
  2. 02探索表结构与数据类型
  3. 03列出集群和数据库
  4. 04时间序列与聚合分析
  5. 05跨候选数据源批量查找表

适用场景

  1. 01分析应用日志与系统日志
  2. 02监控性能指标与趋势变化
  3. 03跨多个集群定位目标表

MCP 相关

该 Skill 通过 Azure MCP 的 Kusto 工具（如 kusto_query、kusto_cluster_list）访问 Azure Data Explorer，并在工具失败时提供 Azure CLI 备用方案。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/microsoft/azure-skills --skill azure-kusto

安装后在 Claude Code 中输入/azure-kusto确认已加载。

详细介绍

Azure Data Explorer (Kusto) 查询与分析

执行 KQL 查询并管理 Azure Data Explorer 资源，以便对日志、遥测和时间序列数据进行快速、可扩展的大数据分析。

概述

此技能支持查询和管理 Azure Data Explorer (Kusto)。这是一项快速且高度可扩展的数据探索服务，针对日志和遥测数据进行了优化。Azure Data Explorer 使用 Kusto Query Language (KQL)，可在数十亿条记录上实现亚秒级查询性能。

主要功能：

  • 查询执行：针对海量数据集运行 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

适用于：事件计数、分布分析、Top-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 最佳实践

🔵 查询模式：

  • 使用 summarize 进行聚合，而不是单独使用 count()
  • 在时间序列中使用 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 工具返回“服务不可用”或连接错误
  • 使用 MCP 工具时出现身份验证失败
  • 已知数据库中有数据，但返回空响应

常见问题

  • 拒绝访问：验证数据库权限（查询至少需要 Viewer 角色）
  • 查询超时：使用时间筛选条件优化查询、缩减结果集或增加超时时间
  • 语法错误：验证 KQL 语法——常见问题包括缺少管道符、运算符不正确
  • 结果为空：检查时间范围筛选条件（可能限制过严），并验证表名
  • 表位置未知：在得出数据不存在的结论前，使用模式 6 批量搜索所有候选来源
  • 找不到集群：检查集群名称格式（去掉“.kusto.windows.net”后缀）
  • CPU 使用率过高：查询范围过广——添加筛选条件、缩短时间范围、限制聚合操作
  • 数据引入延迟：根据引入方式不同，流式数据可能延迟 1–30 秒

使用场景

  • 日志分析：应用程序日志、系统日志、审计日志
  • IoT 分析：传感器数据、设备遥测、实时监控
  • 安全分析：SIEM 数据、威胁检测、安全事件关联分析
  • APM：应用程序性能指标、用户行为、错误跟踪
  • 商业智能：点击流分析、用户分析、运营 KPI

评论

支持 Markdown