name: azure-kusto
description: 使用 KQL 在 Azure Data Explorer（Kusto/ADX）中查询和分析数据，用于日志分析、遥测和时间序列分析。适用场景：KQL 查询、Kusto 数据库查询、Azure Data Explorer、ADX 集群、日志分析、时间序列数据、IoT 遥测、异常检测。
license: MIT
metadata:
    author: Microsoft
    version: "1.1.1"

Azure Data Explorer (Kusto) 查询与分析

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

技能激活触发条件

当用户提出以下请求时，请立即使用本技能：

• “查询我的 Kusto 数据库中的[数据模式]”
• “显示过去一小时内来自 Azure Data Explorer 的事件”
• “分析我的 ADX 集群中的日志”
• “在[数据库]上运行 KQL 查询”
• “我的 Kusto 数据库中有哪些表？”
• “显示[表]的架构”
• “列出我的 Azure Data Explorer 集群”
• “按[维度]聚合遥测数据”
• “从我的日志创建时间序列图表”

关键指示词：

• 提到“Kusto”、“Azure Data Explorer”、“ADX”或“KQL”
• 日志分析或遥测分析请求
• 时间序列数据探索
• IoT 数据分析查询
• SIEM 或安全分析任务
• 对大数据集的聚合请求
• 性能监控或 APM 查询

概述

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

关键能力：

• 查询执行：对大规模数据集运行 KQL 查询
• 架构探索：发现表、列和数据类型
• 资源管理：列出集群和数据库
• 分析：聚合、时间序列、异常检测、机器学习

核心工作流

1. 发现资源：列出订阅中可用的集群和数据库
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

用途：了解数据模型、查询规划

关键数据字段

执行查询时，常见字段模式：

• Timestamp：事件时间 (datetime) - 使用 ago()、between()、bin() 进行时间过滤
• EventType/Category：用于分组的分类字段
• CorrelationId/SessionId：用于追踪相关事件
• Severity/Level：按重要性过滤
• Dimensions：用于分组和过滤的自定义属性

结果格式

查询结果包括：

• 列：字段名称和数据类型
• 行：与查询匹配的数据记录
• 统计信息：行数、执行时间、资源利用率
• 可视化：图表渲染提示（时间图、柱状图等）

KQL 最佳实践

🟢 性能优化：

• 尽早过滤：在连接和聚合之前使用 where
• 限制结果大小：使用 take 或 limit 减少数据传输
• 时间过滤：对于时间序列数据，始终按时间范围过滤
• 索引列：优先过滤索引列

🔵 查询模式：

• 使用 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 工具使用

必需参数：

• 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 执行 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 工具身份验证失败
• 已知数据库中有数据但返回空响应

常见问题

• 访问被拒绝：验证数据库权限（查询至少需要查看者角色）
• 查询超时：使用时间过滤器、减少结果集或增加超时来优化查询
• 语法错误：验证 KQL 语法 - 常见问题：缺少竖线、运算符错误
• 空结果：检查时间范围过滤器（可能过于严格），验证表名
• 集群未找到：检查集群名称格式（不要包含 ".kusto.windows.net" 后缀）
• CPU 使用率高：查询范围过广 - 添加过滤器、减少时间范围、限制聚合
• 引入延迟：根据引入方法，流式数据可能有 1-30 秒的延迟

用例

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