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 集群中的日志"
• "在 [database] 上运行 KQL 查询"
• "我的 Kusto 数据库中有哪些表？"
• "显示 [table] 的架构"
• "列出我的 Azure Data Explorer 集群"
• "按 [dimension] 聚合遥测数据"
• "从我的日志创建时间序列图表"

关键指标：

• 提及 "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：用于分组和筛选的自定义属性

结果格式

查询结果包含：

• 列：字段名称和数据类型
• 行：符合查询条件的数据记录
• 统计信息：行数、执行时间、资源利用率
• 可视化：图表渲染提示 (timechart、barchart 等)

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