Gap-7: Functions Diagnose (B → A) — Trigger + Durable troubleshooting#1641
Gap-7: Functions Diagnose (B → A) — Trigger + Durable troubleshooting#1641paulyuk wants to merge 10 commits into
Conversation
There was a problem hiding this comment.
Pull request overview
Adds new Azure Functions troubleshooting references focused on trigger-specific diagnostics and Durable Functions failure modes, supporting Gap-7 “Functions Diagnose (B → A)” coverage and closing #1615.
Changes:
- Added trigger-specific troubleshooting guide (HTTP, Timer, Queue, Blob, Service Bus, Cosmos DB) with KQL and CLI diagnostics.
- Added Durable Functions troubleshooting guide for stuck orchestrations, non-determinism, task hub conflicts, and retry/timer patterns.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 8 comments.
| File | Description |
|---|---|
| plugin/skills/azure-diagnostics/references/functions/triggers.md | New trigger-focused troubleshooting matrix with KQL/CLI steps per trigger type |
| plugin/skills/azure-diagnostics/references/functions/durable.md | New Durable Functions troubleshooting sections for common operational failure scenarios |
Details# 🔍 Token Analysis Report
fatal: path 'plugin/skills/azure-diagnostics/references/functions/durable.md' exists on disk, but not in 'origin/main' 📊 Token Change ReportComparing Summary
Changed Files
📊 Token Limit Check ReportChecked: 727 files
|
| File | Tokens | Limit | Over By |
|---|---|---|---|
.github/skills/analyze-skill-issues/SKILL.md |
2109 | 500 | +1609 |
.github/skills/analyze-test-run/SKILL.md |
2471 | 500 | +1971 |
.github/skills/file-test-bug/SKILL.md |
628 | 500 | +128 |
.github/skills/sensei/SKILL.md |
856 | 500 | +356 |
.github/skills/skill-authoring/SKILL.md |
839 | 500 | +339 |
.github/skills/vally-eval/SKILL.md |
1757 | 500 | +1257 |
plugin/skills/airunway-aks-setup/SKILL.md |
1025 | 500 | +525 |
plugin/skills/appinsights-instrumentation/SKILL.md |
937 | 500 | +437 |
plugin/skills/azure-ai/SKILL.md |
820 | 500 | +320 |
plugin/skills/azure-aigateway/SKILL.md |
1261 | 500 | +761 |
plugin/skills/azure-aigateway/references/policies.md |
2342 | 2000 | +342 |
plugin/skills/azure-cloud-migrate/SKILL.md |
1085 | 500 | +585 |
plugin/skills/azure-cloud-migrate/references/services/container-apps/cloudrun-deployment-guide.md |
2029 | 2000 | +29 |
plugin/skills/azure-cloud-migrate/references/services/container-apps/deployment-guide.md |
2458 | 2000 | +458 |
plugin/skills/azure-cloud-migrate/references/services/container-apps/fargate-deployment-guide.md |
2587 | 2000 | +587 |
plugin/skills/azure-cloud-migrate/references/services/container-apps/spring-deployment-guide.md |
3871 | 2000 | +1871 |
plugin/skills/azure-cloud-migrate/references/services/functions/lambda-to-functions.md |
2600 | 2000 | +600 |
plugin/skills/azure-cloud-migrate/references/services/functions/runtimes/javascript.md |
2181 | 2000 | +181 |
plugin/skills/azure-compliance/SKILL.md |
1188 | 500 | +688 |
plugin/skills/azure-compute/SKILL.md |
762 | 500 | +262 |
plugin/skills/azure-compute/workflows/essential-machine-management/references/emm-enable-flow.md |
2344 | 2000 | +344 |
plugin/skills/azure-compute/workflows/vm-troubleshooter/vm-troubleshooter.md |
2509 | 2000 | +509 |
plugin/skills/azure-deploy/SKILL.md |
1645 | 500 | +1145 |
plugin/skills/azure-deploy/references/pre-deploy-checklist.md |
4692 | 2000 | +2692 |
plugin/skills/azure-deploy/references/recipes/azd/errors.md |
4004 | 2000 | +2004 |
plugin/skills/azure-deploy/references/troubleshooting.md |
2038 | 2000 | +38 |
plugin/skills/azure-diagnostics/SKILL.md |
1423 | 500 | +923 |
plugin/skills/azure-enterprise-infra-planner/SKILL.md |
911 | 500 | +411 |
plugin/skills/azure-enterprise-infra-planner/references/constraints/compute-apps.md |
2022 | 2000 | +22 |
plugin/skills/azure-kubernetes/SKILL.md |
2634 | 500 | +2134 |
plugin/skills/azure-kubernetes/azure-kubernetes-automatic-readiness/SKILL.md |
3690 | 500 | +3190 |
plugin/skills/azure-kusto/SKILL.md |
2152 | 500 | +1652 |
plugin/skills/azure-messaging/SKILL.md |
821 | 500 | +321 |
plugin/skills/azure-prepare/SKILL.md |
3145 | 500 | +2645 |
plugin/skills/azure-prepare/references/aspire.md |
4617 | 2000 | +2617 |
plugin/skills/azure-prepare/references/plan-template.md |
2560 | 2000 | +560 |
plugin/skills/azure-prepare/references/recipes/azd/aspire.md |
2275 | 2000 | +275 |
plugin/skills/azure-prepare/references/recipes/azd/terraform.md |
3555 | 2000 | +1555 |
plugin/skills/azure-prepare/references/research.md |
2196 | 2000 | +196 |
plugin/skills/azure-prepare/references/resources-limits-quotas.md |
3322 | 2000 | +1322 |
plugin/skills/azure-prepare/references/security.md |
2147 | 2000 | +147 |
plugin/skills/azure-prepare/references/services/functions/bicep.md |
3043 | 2000 | +1043 |
plugin/skills/azure-prepare/references/services/functions/templates/recipes/composition.md |
2813 | 2000 | +813 |
plugin/skills/azure-prepare/references/services/functions/terraform.md |
3404 | 2000 | +1404 |
plugin/skills/azure-quotas/SKILL.md |
3006 | 500 | +2506 |
plugin/skills/azure-quotas/references/commands.md |
2644 | 2000 | +644 |
plugin/skills/azure-reliability/SKILL.md |
5922 | 500 | +5422 |
plugin/skills/azure-reliability/references/configure-multi-region.md |
4729 | 2000 | +2729 |
plugin/skills/azure-reliability/references/services/app-service/reliability.md |
2591 | 2000 | +591 |
plugin/skills/azure-resource-lookup/SKILL.md |
1367 | 500 | +867 |
plugin/skills/azure-resource-visualizer/SKILL.md |
2122 | 500 | +1622 |
plugin/skills/azure-storage/SKILL.md |
1228 | 500 | +728 |
plugin/skills/azure-upgrade/SKILL.md |
1542 | 500 | +1042 |
plugin/skills/azure-upgrade/references/languages/java/INSTRUCTION.md |
2893 | 2000 | +893 |
plugin/skills/azure-upgrade/references/languages/java/package-specific/com.microsoft.azure.management.md |
2428 | 2000 | +428 |
plugin/skills/azure-upgrade/references/languages/java/templates/PLAN_TEMPLATE.md |
2411 | 2000 | +411 |
plugin/skills/azure-upgrade/references/languages/java/templates/PROGRESS_TEMPLATE.md |
2315 | 2000 | +315 |
plugin/skills/azure-upgrade/references/languages/java/templates/SUMMARY_TEMPLATE.md |
2190 | 2000 | +190 |
plugin/skills/azure-upgrade/references/services/functions/automation.md |
3463 | 2000 | +1463 |
plugin/skills/azure-upgrade/references/services/functions/consumption-to-flex.md |
2773 | 2000 | +773 |
plugin/skills/azure-validate/SKILL.md |
950 | 500 | +450 |
plugin/skills/entra-agent-id/SKILL.md |
3994 | 500 | +3494 |
plugin/skills/entra-app-registration/SKILL.md |
2058 | 500 | +1558 |
plugin/skills/entra-app-registration/references/api-permissions.md |
2545 | 2000 | +545 |
plugin/skills/entra-app-registration/references/cli-commands.md |
2211 | 2000 | +211 |
plugin/skills/entra-app-registration/references/console-app-example.md |
2752 | 2000 | +752 |
plugin/skills/entra-app-registration/references/oauth-flows.md |
2375 | 2000 | +375 |
plugin/skills/microsoft-foundry/SKILL.md |
6166 | 500 | +5666 |
plugin/skills/microsoft-foundry/finetuning/SKILL.md |
1375 | 500 | +875 |
plugin/skills/microsoft-foundry/foundry-agent/azd-guidance/references/azd-ai-cli.md |
2129 | 2000 | +129 |
plugin/skills/microsoft-foundry/foundry-agent/create/create-hosted.md |
7101 | 2000 | +5101 |
plugin/skills/microsoft-foundry/foundry-agent/create/quick-start-hosted.md |
5246 | 2000 | +3246 |
plugin/skills/microsoft-foundry/foundry-agent/create/references/foundry-tool-catalog.md |
10891 | 2000 | +8891 |
plugin/skills/microsoft-foundry/foundry-agent/create/references/local-run.md |
2252 | 2000 | +252 |
plugin/skills/microsoft-foundry/foundry-agent/create/references/toolbox-reference.md |
3137 | 2000 | +1137 |
plugin/skills/microsoft-foundry/foundry-agent/create/references/tools.md |
2359 | 2000 | +359 |
plugin/skills/microsoft-foundry/foundry-agent/create/references/use-toolbox-in-hosted-agent.md |
4288 | 2000 | +2288 |
plugin/skills/microsoft-foundry/foundry-agent/deploy/deploy.md |
4897 | 2000 | +2897 |
plugin/skills/microsoft-foundry/foundry-agent/eval-datasets/eval-datasets.md |
2863 | 2000 | +863 |
plugin/skills/microsoft-foundry/foundry-agent/eval-datasets/references/generate-seed-dataset.md |
2212 | 2000 | +212 |
plugin/skills/microsoft-foundry/foundry-agent/eval-datasets/references/trace-to-dataset.md |
4325 | 2000 | +2325 |
plugin/skills/microsoft-foundry/foundry-agent/invocations-ws/invocations-ws.md |
2652 | 2000 | +652 |
plugin/skills/microsoft-foundry/foundry-agent/observe/observe.md |
3856 | 2000 | +1856 |
plugin/skills/microsoft-foundry/foundry-agent/observe/references/continuous-eval.md |
3855 | 2000 | +1855 |
plugin/skills/microsoft-foundry/foundry-agent/observe/references/evaluate-step.md |
2175 | 2000 | +175 |
plugin/skills/microsoft-foundry/foundry-agent/observe/references/evaluation-suite-generation.md |
3134 | 2000 | +1134 |
plugin/skills/microsoft-foundry/foundry-agent/routine/routine.md |
2032 | 2000 | +32 |
plugin/skills/microsoft-foundry/foundry-agent/trace/references/kql-templates.md |
2701 | 2000 | +701 |
plugin/skills/microsoft-foundry/models/deploy-model/SKILL.md |
1805 | 500 | +1305 |
plugin/skills/microsoft-foundry/models/deploy-model/capacity/SKILL.md |
1739 | 500 | +1239 |
plugin/skills/microsoft-foundry/models/deploy-model/customize/SKILL.md |
2235 | 500 | +1735 |
plugin/skills/microsoft-foundry/models/deploy-model/customize/references/customize-workflow.md |
3335 | 2000 | +1335 |
plugin/skills/microsoft-foundry/models/deploy-model/preset/SKILL.md |
1226 | 500 | +726 |
plugin/skills/microsoft-foundry/models/deploy-model/preset/references/preset-workflow.md |
5534 | 2000 | +3534 |
plugin/skills/microsoft-foundry/project/create/create-foundry-project.md |
2283 | 2000 | +283 |
plugin/skills/microsoft-foundry/quota/quota.md |
2288 | 2000 | +288 |
plugin/skills/microsoft-foundry/quota/references/capacity-planning.md |
2080 | 2000 | +80 |
plugin/skills/microsoft-foundry/references/agent-metadata-contract.md |
2217 | 2000 | +217 |
plugin/skills/microsoft-foundry/references/sdk/foundry-sdk-py.md |
2162 | 2000 | +162 |
plugin/skills/python-appservice-deploy/SKILL.md |
688 | 500 | +188 |
Consider moving content to
references/subdirectories.
Automated token analysis. See skill authoring guidelines for best practices.
jongio
left a comment
jongio
left a comment
There was a problem hiding this comment.
Solid troubleshooting reference docs for Durable Functions and trigger types. The coverage is thorough across 6 trigger types and 4 Durable scenarios. A few issues to address before merge - two CI blockers and some technical accuracy items.
CI Blockers:
SKILL.mdversion needs bump from1.0.4to1.0.5- Both new files need links from SKILL.md References and/or
functions/README.md
New findings (not covered by existing bot comments): see inline comments.
Existing bot feedback: 7 of 8 bot comments are valid and should be addressed. The || table formatting flag (triggers.md:9) appears to be a false positive - those || are JMESPath OR operators inside bash code blocks, not markdown table syntax.
- Fix HTTP timeout guidance: distinguish execution vs gateway timeouts, recommend async patterns for long-running work - Fix Timer trigger config: remove incorrect isSingleton, use proper singleton/useMonitor settings - Fix Service Bus DLQ command: replace wrong auth-rule command with guidance to use Service Bus Explorer or SDK - Fix BSD-specific date command: add portable GNU/BSD date fallback - Fix Task.Delay description: focus on replay-safety not thread blocking - Fix task hub diagnostics: query correct app setting for hub name override - Fix hub name example: remove hyphens (must be alphanumeric only) - Expand storage tip: document full set of task hub storage artifacts - Fix history table query: relabel as existence check, add per-instance history size query Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Bump SKILL.md version from 1.0.4 to 1.0.5 - Add triggers.md and durable.md links to SKILL.md References section - Add Additional References section to functions/README.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
These sub-guides are already linked from functions/README.md, which matches the existing pattern: sub-topic guides are linked from their service README, not from the top-level SKILL.md References section. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds Azure Functions “trigger-specific” and “Durable Functions” troubleshooting reference docs to support the “Gap-7: Functions Diagnose (B → A)” assessment.
Changes:
- Added a new trigger-specific troubleshooting guide with symptom/cause/fix matrices, KQL, and CLI diagnostics.
- Added a new Durable Functions troubleshooting guide covering stuck instances, non-determinism, task hub conflicts, and retry/timer patterns.
- Linked the new references from the Functions README and bumped the skill version.
Show a summary per file
| File | Description |
|---|---|
| plugin/skills/azure-diagnostics/references/functions/triggers.md | New trigger-focused troubleshooting reference (HTTP/Timer/Queue/Blob/Service Bus/Cosmos). |
| plugin/skills/azure-diagnostics/references/functions/durable.md | New Durable Functions troubleshooting reference (stuck, non-determinism, hubs, retry/timers). |
| plugin/skills/azure-diagnostics/references/functions/README.md | Adds “Additional References” links to the two new docs. |
| plugin/skills/azure-diagnostics/SKILL.md | Bumps skill version to reflect new content. |
Copilot's findings
- Files reviewed: 4/4 changed files
- Comments generated: 4
jongio
left a comment
jongio
left a comment
There was a problem hiding this comment.
Previous feedback all addressed - nice work on the fixes, especially the portable date fallback and the expanded storage artifacts tip.
Two items worth fixing before merge (both flagged by the bot review, confirming they're real):
-
triggers.md:17 -
resultCode >= 400does string comparison in KQL sinceresultCodeis typed as string in App Insights. This would miss 5xx errors in some cases. Fix:toint(resultCode) >= 400 -
triggers.md Cosmos DB section - "Set unique
LeaseContainerPrefixper function app in host.json" is inaccurate.leaseContainerPrefixis a per-trigger binding attribute (set in the trigger attribute in C# or infunction.json), not ahost.jsonsetting. Users following this would put config in the wrong place.
The other two unresolved bot comments (double-pipe table formatting in durable.md, PR description file count) are false positives - the tables render fine and the PR description is reasonable.
- Fix KQL resultCode comparison: cast to int with toint() since Application Insights stores resultCode as a string - Fix Cosmos DB duplicate processing guidance: reference leaseContainerPrefix on the trigger binding instead of host.json Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
jongio
left a comment
jongio
left a comment
There was a problem hiding this comment.
Both items I flagged last time are fixed. KQL uses toint(resultCode) >= 400 and the Cosmos DB guidance now points at the trigger binding instead of host.json. No new findings. LGTM.
jongio
left a comment
jongio
left a comment
There was a problem hiding this comment.
My prior feedback is all addressed - KQL uses toint(), Cosmos leaseContainerPrefix points to the trigger binding, hub name is alphanumeric. Content hasn't changed since my previous review.
Two new items - see inline comments.
The 6 open bot threads are mostly minor wording nits. The NCrontab reference (triggers.md:37) is the most worth fixing.
|
This PR has been automatically closed because it has unresolved review comments and no new commits in the last 28 days. If you would still like to merge these changes, please:
Thank you for your contribution! |
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
|
Reopened and pushed e2aed9b addressing all outstanding review comments on this PR. Every unresolved thread has been resolved. Validators run locally: frontmatter and references pass, targeted skill tests pass, and the changed files are within token budget (the repo-wide |
jongio
left a comment
jongio
left a comment
There was a problem hiding this comment.
nit: one optional wording suggestion below
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
|
Note on the red |
jongio
left a comment
jongio
left a comment
There was a problem hiding this comment.
One copy-paste concern flagged inline.
|
Hi @jongio, first business day back after the July 4th weekend. This is ready for review when you have a moment. The only red check is the pre-existing repo-wide eval failure, already fixed on main by the vally 0.7.0 update (#2759), so it just needs a re-run to go green. An approval would let it land. Thanks! |
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
| | Trigger not firing | Lease container missing | Create lease container (default: `leases`) in same database | | ||
| | Change feed lag | Insufficient RU/s on lease container | Increase RU/s on leases container or enable autoscale | | ||
| | Duplicate processing | Multiple apps share lease container | Configure a unique `leaseContainerPrefix` on each Cosmos DB trigger binding per function app, or use separate lease containers | | ||
| | Partial document data | Projection or TTL conflict | Ensure `StartFromBeginning` config and verify no TTL on lease container | |
There was a problem hiding this comment.
StartFromBeginning cannot resolve a partial document payload. It only changes where a trigger first starts reading, and it is ignored after leases or checkpoints exist. TTL on the lease container is also unrelated to the document payload, so this row directs operators toward a remediation that cannot fix the symptom. Replace it with a payload-specific diagnosis, such as inspecting the binding or deserialization/projection configuration.
| |---------|-------|-----| | ||
| | Timer fires immediately on replay | Using `Task.Delay` instead of durable timer | Replace with `context.CreateTimer(fireAt, cancellationToken)` | | ||
| | Retry storms | `maxNumberOfAttempts` too high with short intervals | Use exponential backoff: `CallActivityWithRetryAsync` with `RetryOptions` | | ||
| | Sub-orchestration timeout | No timeout set on `CallSubOrchestratorAsync` | Wrap in `Task.WhenAny` with `context.CreateTimer` as deadline | |
There was a problem hiding this comment.
Task.WhenAny needs a cancellation path that this guidance omits. When CallSubOrchestratorAsync completes first, the durable timer remains outstanding and keeps the parent orchestration in Running until the deadline. When the timer wins, the sub-orchestration also keeps running. Show canceling the timer on the success path, and state that a timed-out sub-orchestration must be terminated explicitly when that is required.
Closes #1615 | Parent: #1608
3 files: README.md (links the Functions references), triggers.md (HTTP, Timer, Queue, Blob, Service Bus, Cosmos trigger troubleshooting), durable.md (stuck orchestrations, non-determinism, task hub conflicts).