Efficient Appinsights Handler

Query, analyze, and manage Azure Application Insights telemetry data with optimized KQL queries and alert configuration.

When to Use This Command

Run this command when you need to:

• Query Application Insights logs, metrics, and traces using KQL from the command line
• Set up or modify alert rules and action groups for application monitoring
• Export telemetry data for analysis or generate performance summary reports

Consider alternatives when:

• You need to provision a new Application Insights resource (use Azure CLI or Bicep templates directly)
• You require real-time streaming dashboards (use Azure Portal or Grafana integration)

Quick Start

Configuration

Copy
name: efficient-appinsights-handler
type: command
category: azure

Example Invocation

Copy
claude command:run efficient-appinsights-handler --query "requests | where resultCode >= 500" --timerange 24h

Example Output

[AppInsights] Connected to resource: myapp-prod-insights
[Query] Executing KQL over last 24 hours...

| Timestamp           | Operation    | ResultCode | Duration(ms) | URL                    |
|---------------------|------------- |------------|--------------|------------------------|
| 2026-03-15 08:12:03 | POST /api/v2 | 500        | 2341         | /api/v2/orders         |
| 2026-03-15 09:45:21 | GET /api/v2  | 503        | 30002        | /api/v2/inventory      |
| 2026-03-15 14:02:18 | POST /api/v2 | 500        | 1892         | /api/v2/orders         |

[Summary] 3 server errors in 24h | Avg duration: 11,411ms | Top endpoint: /api/v2/orders (2 errors)

Core Concepts

Application Insights Overview

Aspect	Details
Data Types	Requests, dependencies, exceptions, traces, custom events, metrics
Query Language	Kusto Query Language (KQL) for log analytics
Alerting	Metric alerts, log alerts, smart detection, action groups
Retention	Default 90 days; configurable up to 730 days

Query Workflow

[Authenticate] --> Azure CLI / Service Principal
       |
[Select Resource] --> App Insights instance
       |
[Build KQL Query] --> Filter + aggregate
       |
[Execute + Format] --> Table / JSON / CSV
       |
[Optional: Create Alert] --> Threshold + action group

Configuration

Parameter	Type	Default	Description
query	string	required	KQL query string or path to a .kql file
timerange	string	1h	Time range for the query (1h, 24h, 7d, 30d, custom)
resource	string	auto	Application Insights resource name or ID
format	string	table	Output format: table, json, or csv
alert	boolean	false	Create an alert rule based on the query results

Best Practices

1. Use Time Filters Early in Queries - Place where timestamp > ago(24h) at the beginning of your KQL query. Application Insights processes filters left to right, and early time bounds dramatically reduce scanned data.

2. Summarize Before Rendering - Use summarize count() by bin(timestamp, 1h) to aggregate large result sets. Pulling raw rows for high-traffic applications can timeout or produce unreadable output.

3. Save Reusable Queries as Files - Store frequently used KQL queries as .kql files in your repository. Reference them by path instead of typing inline, ensuring consistency and version control.

4. Set Meaningful Alert Thresholds - Base alert thresholds on historical baselines, not arbitrary numbers. Query the last 30 days of data to understand normal variance before setting upper bounds.

5. Correlate Across Telemetry Types - Join requests with dependencies and exceptions using operation_Id to get the full picture of a failure. Isolated queries miss the causal chain.

Common Issues

1. Query Returns No Results - Verify the time range covers the period of interest. Application Insights timestamps are UTC; local time mismatches are the most common cause of empty results.

2. Authentication Fails with 403 - Ensure your Azure CLI session has the Log Analytics Reader role on the Application Insights resource. Run az login to refresh expired credentials.

3. Alert Fires Too Frequently - Noisy alerts indicate thresholds are too sensitive. Add aggregation windows (bin(timestamp, 5m)) and minimum occurrence counts to reduce false positives.