查询模式

模式 1：基本数据检索

通过简单筛选从表中获取最近的记录。

示例 KQL：

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

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

模式 2：聚合分析

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

示例 KQL：

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

适用于：事件计数、分布分析、前 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：用于分组和筛选的自定义属性

结果格式

查询结果包括：

• Columns：字段名称和数据类型
• Rows：匹配查询的数据记录
• Statistics：行数、执行时间、资源利用率
• Visualization：图表渲染提示 (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

每周安装量

102.5K

代码仓库

microsoft/githu…or-azure

GitHub 星标数

143

首次出现

2026年2月4日

安全审计

Gen Agent Trust HubPassSocketPassSnykPass

安装于

github-copilot102.4K

codex256

gemini-cli246

opencode230

cursor219

kimi-cli216

Core Workflow

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

Query Patterns

Pattern 1: Basic Data Retrieval

Fetch recent records from a table with simple filtering.

Example KQL :

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

Use for : Quick data inspection, recent event retrieval

Pattern 2: Aggregation Analysis

Summarize data by dimensions for insights and reporting.

Example KQL :

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

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

Pattern 3: Time Series Analytics

Analyze data over time windows for trends and patterns.

Example 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

Pattern 4: Join and Correlation

Combine multiple tables for cross-dataset analysis.

Example 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

Pattern 5: Schema Discovery

Explore table structure before querying.

Tools : kusto_table_schema_get

Use for : Understanding data model, query planning

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

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.)

KQL Best Practices

🟢 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

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

MCP Tools Used

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

Fallback Strategy: Azure CLI Commands

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

CLI Command Reference

KQL Query via Azure CLI

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

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

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

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

Weekly Installs

102.5K

Repository

microsoft/githu…or-azure

GitHub Stars

143

First Seen

Feb 4, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

github-copilot102.4K

codex256

gemini-cli246

opencode230

cursor219

kimi-cli216