Debug traces an APIM request to analyze policy execution flow. Use when the user wants to trace, debug, or diagnose an APIM API request to understand why it failed, how policies executed, or what happened during request processing. The user provides the full HTTP request to trace, and the skill automatically obtains Azure credentials, enables APIM debug tracing, sends the request, retrieves the trace, and analyzes results. Triggers on phrases like "trace this request", "debug this API call", "why did this request fail", "analyze APIM policy execution", or "debug tracing".
Sends an APIM request with debug tracing enabled, retrieves the full policy execution trace, and analyzes the results.
azd up completed (generates .vscode/settings.json with apim_resource_id)az login)pwsh)Prompt the user to provide the full HTTP request to trace. The user should supply:
api-key, Authorization)Resolve any {{variable}} placeholders using values from .vscode/settings.json under rest-client.environmentVariables. Common variables:
| Placeholder |
|---|
| Source |
|---|
{{apim_gateway_url}} | .vscode/settings.json |
{{apim_subscription_key}} | .vscode/settings.json |
Write a JSON file to Tests/Results/.debug-request.json:
{
"method": "POST",
"url": "https://<resolved-apim-url>/unified-ai/openai/deployments/gpt-4.1-mini/chat/completions?api-version=2025-01-01-preview",
"headers": {
"api-key": "<resolved-subscription-key>",
"Content-Type": "application/json"
},
"body": "{\"model\":\"gpt-4.1-mini\",\"messages\":[{\"role\":\"user\",\"content\":\"test\"}],\"max_tokens\":50}"
}
All {{variable}} placeholders must be resolved before writing the file. Read .vscode/settings.json to resolve them.
pwsh -File .github/skills/apim-debug-tracer/scripts/debug-trace.ps1 -RequestFile Tests/Results/.debug-request.json
The script automatically:
az account get-access-token (current logged-in user)Apim-Debug-Authorization header for tracingApim-Trace-Id from the responseTests/Results/.debug-trace-output.jsonRead Tests/Results/.debug-trace-output.json and analyze the results.
If the request succeeded (2xx status):
If the request failed (4xx/5xx status):
source, message, data fields)If no trace was returned:
apim_resource_id is correct in settingsaz login if token acquisition failedDelete temp files after analysis:
Remove-Item "Tests/Results/.debug-request.json" -ErrorAction SilentlyContinue
Remove-Item "Tests/Results/.debug-trace-output.json" -ErrorAction SilentlyContinue