1---
2name: azure-diagnostics
3description: "Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, troubleshoot functions, troubleshoot AKS, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, service bus dead letter."
4license: MIT
5metadata:
6  author: Microsoft
7  version: "1.1.4"
8---
9 
10# Azure Diagnostics
11 
12> **AUTHORITATIVE GUIDANCE — MANDATORY COMPLIANCE**
13>
14> This document is the **official source** for debugging and troubleshooting Azure production issues. Follow these instructions to diagnose and resolve common Azure service problems systematically.
15 
16## Triggers
17 
18Activate this skill when user wants to:
19- Debug or troubleshoot production issues
20- Diagnose errors in Azure services
21- Analyze application logs or metrics
22- Fix image pull, cold start, or health probe issues
23- Investigate why Azure resources are failing
24- Find root cause of application errors
25- Troubleshoot App Service issues (high CPU, deployment failures, crashes, slow responses, TLS/custom domains)
26- Respond to prompts like "troubleshoot app service", "app service high CPU", or "app service deployment failure"
27- Troubleshoot Azure Function Apps (invocation failures, timeouts, binding errors)
28- Find the App Insights or Log Analytics workspace linked to a Function App
29- Troubleshoot AKS clusters, nodes, pods, ingress, or Kubernetes networking issues
30- Troubleshoot Azure Messaging SDK issues (Event Hubs, Service Bus connection failures, AMQP errors, message lock issues)
31 
32## Rules
33 
341. Start with systematic diagnosis flow
352. Use AppLens (MCP) for AI-powered diagnostics when available
363. Check resource health before deep-diving into logs
374. Select appropriate troubleshooting guide based on service type
385. Document findings and attempted remediation steps
396. Route AKS incidents to the dedicated AKS troubleshooting document
40 
41---
42 
43## Quick Diagnosis Flow
44 
451. **Identify symptoms** - What's failing?
462. **Check resource health** - Is Azure healthy?
473. **Review logs** - What do logs show?
484. **Analyze metrics** - Performance patterns?
495. **Investigate recent changes** - What changed?
50 
51---
52 
53## Troubleshooting Guides by Service
54 
55| Service | Common Issues | Reference |
56|---------|---------------|-----------|
57| **Container Apps** | Image pull failures, cold starts, health probes, port mismatches | [container-apps/](references/container-apps/README.md) |
58| **App Service** | High CPU, deployment failures, crashes, slow responses, TLS/custom domains | [app-service/](references/app-service/README.md) |
59| **Function Apps** | App details, invocation failures, timeouts, binding errors, cold starts, missing app settings | [functions/](references/functions/README.md) |
60| **AKS** | Cluster access, nodes, `kube-system`, scheduling, crash loops, ingress, DNS, upgrades | [AKS Troubleshooting](troubleshooting/aks/aks-troubleshooting.md) |
61| **Messaging** | Event Hubs & Service Bus SDK errors, AMQP failures, message lock, connectivity | [Messaging Troubleshooting](troubleshooting/messaging/README.md) |
62 
63---
64 
65## Routing
66 
67- Keep Container Apps and Function Apps diagnostics in this parent skill.
68- Route active AKS incidents, AKS-specific intake, evidence gathering, and remediation guidance to [AKS Troubleshooting](troubleshooting/aks/aks-troubleshooting.md).
69- Route Azure Messaging SDK troubleshooting (Event Hubs, Service Bus) to [Messaging Troubleshooting](troubleshooting/messaging/README.md).
70 
71---
72 
73## Quick Reference
74 
75### Common Diagnostic Commands
76 
77```bash
78# Check resource health
79az resource show --ids RESOURCE_ID
80# View activity log
81az monitor activity-log list -g RG --max-events 20
82# Container Apps logs
83az containerapp logs show --name APP -g RG --follow
84# Function App logs (query App Insights traces)
85az monitor app-insights query --apps APP-INSIGHTS -g RG \
86  --analytics-query "traces | where timestamp > ago(1h) | order by timestamp desc | take 50"
87```
88 
89### AppLens (MCP Tools)
90 
91For AI-powered diagnostics, use:
92```
93mcp_azure_mcp_applens
94  intent: "diagnose issues with <resource-name>"
95  command: "diagnose"
96  parameters:
97    resourceId: "<resource-id>"
98 
99Provides:
100- Automated issue detection
101- Root cause analysis
102- Remediation recommendations
103```
104 
105### Azure Monitor (MCP Tools)
106 
107For querying logs and metrics:
108```
109mcp_azure_mcp_monitor
110  intent: "query logs for <resource-name>"
111  command: "logs_query"
112  parameters:
113    workspaceId: "<workspace-id>"
114    query: "<KQL-query>"
115```
116 
117See [kql-queries.md](references/kql-queries.md) for common diagnostic queries.
118 
119---
120 
121## Check Azure Resource Health
122 
123### Using MCP
124 
125```
126mcp_azure_mcp_resourcehealth
127  intent: "check health status of <resource-name>"
128  command: "get"
129  parameters:
130    resourceId: "<resource-id>"
131```
132 
133### Using CLI
134 
135```bash
136# Check specific resource health
137az resource show --ids RESOURCE_ID
138 
139# Check recent activity
140az monitor activity-log list -g RG --max-events 20
141```
142 
143---
144 
145## References
146 
147- [KQL Query Library](references/kql-queries.md)
148- [Azure Resource Graph Queries](references/azure-resource-graph.md)
149- [App Service Troubleshooting](references/app-service/README.md)
150- [Function Apps Troubleshooting](references/functions/README.md)
151- [Messaging Troubleshooting](troubleshooting/messaging/README.md)
152