azure-kusto

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Azure Data Explorer (Kusto) Query & Analytics

Azure Data Explorer（Kusto）查询与分析

Execute KQL queries and manage Azure Data Explorer resources for fast, scalable big data analytics on log, telemetry, and time series data.

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

Skill Activation Triggers

技能激活触发条件

Use this skill immediately when the user asks to:

"Query my Kusto database for [data pattern]"
"Show me events in the last hour from Azure Data Explorer"
"Analyze logs in my ADX cluster"
"Run a KQL query on [database]"
"What tables are in my Kusto database?"
"Show me the schema for [table]"
"List my Azure Data Explorer clusters"
"Aggregate telemetry data by [dimension]"
"Create a time series chart from my logs"

Key Indicators:

Mentions "Kusto", "Azure Data Explorer", "ADX", or "KQL"
Log analytics or telemetry analysis requests
Time series data exploration
IoT data analysis queries
SIEM or security analytics tasks
Requests for data aggregation on large datasets
Performance monitoring or APM queries

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

"查询我的Kusto数据库中符合[data pattern]的数据"
"展示我Azure Data Explorer中过去一小时内的事件"
"分析我ADX集群中的日志"
"在[database]上运行KQL查询"
"我的Kusto数据库中有哪些表？"
"展示[table]的架构"
"列出我的Azure Data Explorer集群"
"按[dimension]聚合遥测数据"
"从我的日志中生成时间序列图表"

关键识别指标：

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

Overview

概述

This skill enables querying and managing Azure Data Explorer (Kusto), a fast and highly scalable data exploration service optimized for log and telemetry data. Azure Data Explorer provides sub-second query performance on billions of records using the Kusto Query Language (KQL).

Key capabilities:

Query Execution: Run KQL queries against massive datasets
Schema Exploration: Discover tables, columns, and data types
Resource Management: List clusters and databases
Analytics: Aggregations, time series, anomaly detection, machine learning

此技能支持查询和管理Azure Data Explorer（Kusto），这是一款针对日志和遥测数据优化的快速、高可扩展性数据探索服务。Azure Data Explorer使用Kusto查询语言（KQL），可对数十亿条记录实现亚秒级查询性能。

核心功能：

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

Core Workflow

核心工作流

Discover Resources: List available clusters and databases in subscription
Explore Schema: Retrieve table structures to understand data model
Query Data: Execute KQL queries for analysis, filtering, aggregation
Analyze Results: Process query output for insights and reporting

发现资源：列出订阅中的可用集群和数据库
探索架构：检索表结构以理解数据模型
查询数据：执行KQL查询进行分析、过滤、聚合
分析结果：处理查询输出以获取洞察和生成报告

Query Patterns

查询模式

Pattern 1: Basic Data Retrieval

模式1：基础数据检索

Fetch recent records from a table with simple filtering.

Example KQL:

kql

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

Use for: Quick data inspection, recent event retrieval

从表中获取带简单过滤条件的近期记录。

示例KQL:

kql

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

适用场景：快速数据检查、近期事件检索

Pattern 2: Aggregation Analysis

模式2：聚合分析

Summarize data by dimensions for insights and reporting.

Example KQL:

kql

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

Use for: Event counting, distribution analysis, top-N queries

按维度汇总数据以获取洞察和生成报告。

示例KQL:

kql

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

适用场景：事件计数、分布分析、Top-N查询

Pattern 3: Time Series Analytics

模式3：时间序列分析

Analyze data over time windows for trends and patterns.

Example KQL:

kql

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

Use for: Performance monitoring, trend analysis, anomaly detection

按时间窗口分析数据以发现趋势和模式。

示例KQL:

kql

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

适用场景：性能监控、趋势分析、异常检测

Pattern 4: Join and Correlation

模式4：关联查询

Combine multiple tables for cross-dataset analysis.

Example KQL:

kql

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

Use for: Root cause analysis, correlated event tracking

合并多个表进行跨数据集分析。

示例KQL:

kql

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

适用场景：根因分析、关联事件追踪

Pattern 5: Schema Discovery

模式5：架构发现

Explore table structure before querying.

Tools:

kusto_table_schema_get

Use for: Understanding data model, query planning

在查询前探索表结构。

工具：

kusto_table_schema_get

适用场景：理解数据模型、查询规划

Key Data Fields

关键数据字段

When executing queries, common field patterns:

Timestamp: Time of event (datetime) - use
```
ago()
```
,
```
between()
```
,
```
bin()
```
for time filtering
EventType/Category: Classification field for grouping
CorrelationId/SessionId: For tracing related events
Severity/Level: For filtering by importance
Dimensions: Custom properties for grouping and filtering

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

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

Result Format

结果格式

Query results include:

Columns: Field names and data types
Rows: Data records matching query
Statistics: Row count, execution time, resource utilization
Visualization: Chart rendering hints (timechart, barchart, etc.)

查询结果包含：

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

KQL Best Practices

KQL最佳实践

🟢 Performance Optimized:

Filter early: Use
```
where
```
before joins and aggregations
Limit result size: Use
```
take
```
or
```
limit
```
to reduce data transfer
Time filters: Always filter by time range for time series data
Indexed columns: Filter on indexed columns first

🔵 Query Patterns:

Use
```
summarize
```
for aggregations instead of
```
count()
```
alone
Use
```
bin()
```
for time bucketing in time series
Use
```
project
```
to select only needed columns
Use
```
extend
```
to add calculated fields

🟡 Common Functions:

```
ago(timespan)
```
: Relative time (ago(1h), ago(7d))
```
between(start .. end)
```
: Range filtering
```
startswith()
```
,
```
contains()
```
,
```
matches regex
```
: String filtering
```
parse
```
,
```
extract
```
: Extract values from strings
```
percentiles()
```
,
```
avg()
```
,
```
sum()
```
,
```
max()
```
,
```
min()
```
: Aggregations

🟢 性能优化：

尽早过滤：在连接和聚合前使用
```
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()
```
：聚合函数

Best Practices

最佳实践

Always include time range filters to optimize query performance
Use
```
take
```
or
```
limit
```
for exploratory queries to avoid large result sets
Leverage
```
summarize
```
for aggregations instead of client-side processing
Store frequently-used queries as functions in the database
Use materialized views for repeated aggregations
Monitor query performance and resource consumption
Apply data retention policies to manage storage costs
Use streaming ingestion for real-time analytics (< 1 second latency)
Integrate with Azure Monitor for operational insights

始终包含时间范围过滤以优化查询性能
探索性查询使用
```
take
```
或
```
limit
```
以避免返回过大结果集
利用
```
summarize
```
进行聚合，而非客户端侧处理
将常用查询存储为数据库中的函数
对重复聚合使用物化视图
监控查询性能和资源消耗
应用数据保留策略以管理存储成本
使用流式摄入进行实时分析（延迟<1秒）
与Azure Monitor集成以获取运营洞察

MCP Tools Used

使用的MCP工具

Tool	Purpose
`kusto_cluster_list`	List all Azure Data Explorer clusters in a subscription
`kusto_database_list`	List all databases in a specific Kusto cluster
`kusto_query`	Execute KQL queries against a Kusto database
`kusto_table_schema_get`	Retrieve schema information for a specific table

Required Parameters:

```
subscription
```
: Azure subscription ID or display name
```
cluster
```
: Kusto cluster name (e.g., "mycluster")
```
database
```
: Database name
```
query
```
: KQL query string (for query operations)
```
table
```
: Table name (for schema operations)

Optional Parameters:

```
resource-group
```
: Resource group name (for listing operations)
```
tenant
```
: Azure AD tenant ID

工具	用途
`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

Fallback Strategy: Azure CLI Commands

回退策略：Azure CLI命令

If Azure MCP Kusto tools fail, timeout, or are unavailable, use Azure CLI commands as fallback.

如果Azure MCP Kusto工具失败、超时或不可用，请使用Azure CLI命令作为回退方案。

CLI Command Reference

CLI命令参考

Operation	Azure CLI Command
List clusters	`az kusto cluster list --resource-group <rg-name>`
List databases	`az kusto database list --cluster-name <cluster> --resource-group <rg-name>`
Show cluster	`az kusto cluster show --name <cluster> --resource-group <rg-name>`
Show database	`az kusto database show --cluster-name <cluster> --database-name <db> --resource-group <rg-name>`

操作	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>`

KQL Query via Azure CLI

通过Azure CLI执行KQL查询

For queries, use the Kusto REST API or direct cluster URL:

bash

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

对于查询操作，使用Kusto REST API或直接集群URL：

bash

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

When to Fallback

何时使用回退方案

Switch to Azure CLI when:

MCP tool returns timeout error (queries > 60 seconds)
MCP tool returns "service unavailable" or connection errors
Authentication failures with MCP tools
Empty response when database is known to have data

当出现以下情况时切换到Azure CLI：

MCP工具返回超时错误（查询>60秒）
MCP工具返回“服务不可用”或连接错误
MCP工具认证失败
已知数据库有数据但返回空响应

Common Issues

常见问题

Access Denied: Verify database permissions (Viewer role minimum for queries)
Query Timeout: Optimize query with time filters, reduce result set, or increase timeout
Syntax Error: Validate KQL syntax - common issues: missing pipes, incorrect operators
Empty Results: Check time range filters (may be too restrictive), verify table name
Cluster Not Found: Check cluster name format (exclude ".kusto.windows.net" suffix)
High CPU Usage: Query too broad - add filters, reduce time range, limit aggregations
Ingestion Lag: Streaming data may have 1-30 second delay depending on ingestion method

访问被拒绝：验证数据库权限（查询至少需要Viewer角色）
查询超时：使用时间过滤优化查询、减少结果集或增加超时时间
语法错误：验证KQL语法 - 常见问题：缺少管道符、运算符错误
空结果：检查时间范围过滤（可能过于严格）、验证表名称
集群未找到：检查集群名称格式（排除".kusto.windows.net"后缀）
CPU使用率过高：查询范围过广 - 添加过滤条件、缩小时间范围、限制聚合
摄入延迟：流式数据可能有1-30秒延迟，具体取决于摄入方式

Use Cases

适用场景

Log Analytics: Application logs, system logs, audit logs
IoT Analytics: Sensor data, device telemetry, real-time monitoring
Security Analytics: SIEM data, threat detection, security event correlation
APM: Application performance metrics, user behavior, error tracking
Business Intelligence: Clickstream analysis, user analytics, operational KPIs

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