[App Service] `az webapp troubleshoot status`: provide latest application startup attempt data by aamos-company · Pull Request #33673 · Azure/azure-cli

aamos-company · 2026-06-29T21:23:10Z

Related command

az webapp troubleshoot status

Description

Introduces the az webapp troubleshoot status command for diagnosing Linux web apps without leaving the terminal.

`az webapp troubleshoot status`

Reports per-instance runtime health and recent startup outcomes for a Linux web app.

Data sources

• Site Runtime Status — ARM GET .../sites/{name}[/slots/{slot}]/siteStatus[/{instanceId}]?api-version=2024-11-01
• Per-instance startup summary — KuduLite GET https://{scm-host}/api/startuplogs/summary[?instance={id}]
• Machine-name ↔ ARM hex id mapping — ARM /instances , so --instance accepts either form.

What it surfaces

• Per-instance State + Details, LastError / LastErrorDetails / LastErrorTimestamp (hidden for Started instances or when there have been no failed startups in the report window), and the last 24h Succeeded / Failed / most-recent-attempt counts.
• Handles KuduLite SummaryFetchStatus failures gracefully (missing startup summary is reported per instance, not silently zeroed).
• Correlates orphan startup entries (instances the log endpoint knows about but ARM no longer lists) so nothing is dropped.

Testing Guide
Images attached in the comments

This checklist is used to make sure that common guidelines for a pull request are followed.

The PR title and description has followed the guideline in Submitting Pull Requests.
I adhere to the Command Guidelines.
I adhere to the Error Handling Guidelines.

azure-client-tools-bot-prd · 2026-06-29T21:23:13Z

Validation for Azure CLI Full Test Starting...

Thanks for your contribution!

azure-client-tools-bot-prd · 2026-06-29T21:23:16Z

Hi @aamos-company,
Since the current milestone time is less than 7 days, this pr will be reviewed in the next milestone.

azure-client-tools-bot-prd · 2026-06-29T21:23:19Z

Validation for Breaking Change Starting...

Thanks for your contribution!

microsoft-github-policy-service · 2026-06-29T21:23:44Z

Thank you for your contribution @aamos-company! We will review the pull request and get back to you soon.

Copilot

Pull request overview

This PR extends the App Service command module with new runtime-status troubleshooting capabilities by introducing a webapp status command (ARM siteStatus) and a preview webapp troubleshoot status command (ARM siteStatus + SCM startup summary), plus associated help, params, and tests.

Changes:

Add az webapp status to fetch per-instance Site Runtime Status (ARM siteStatus), including --instance filtering and table formatting.
Add preview az webapp troubleshoot status to combine ARM runtime status with SCM startup summary, rendered as a human-readable report for table output.
Add scenario + mocked tests and a new recording; update HISTORY entry.

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/azure-cli/HISTORY.rst	Adds history note for the new `az webapp status` command.
src/azure-cli/azure/cli/command_modules/appservice/tests/latest/test_webapp_commands.py	Adds live scenario coverage for `az webapp status`.
src/azure-cli/azure/cli/command_modules/appservice/tests/latest/test_webapp_commands_thru_mock.py	Adds mocked unit tests for `troubleshoot status`, `webapp status`, and output transform behavior.
src/azure-cli/azure/cli/command_modules/appservice/tests/latest/recordings/test_webapp_status.yaml	Adds VCR recording for the new scenario test.
src/azure-cli/azure/cli/command_modules/appservice/custom.py	Implements `show_webapp_status`, `troubleshoot_status`, formatting, and status-tip logging.
src/azure-cli/azure/cli/command_modules/appservice/commands.py	Registers new commands and table transformers.
src/azure-cli/azure/cli/command_modules/appservice/_params.py	Adds `--instance` parameter wiring for `webapp status` and `webapp troubleshoot status`.
src/azure-cli/azure/cli/command_modules/appservice/_help.py	Adds help for `webapp status` and the preview `webapp troubleshoot` group/command.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+        for item in runtime_items:
+            _fetch_startup_summary(item)
+
+    # --- 3. Assemble payload ---


yonzhan · 2026-06-30T00:55:31Z

App Service

- Correlate ARM /siteStatus items with KuduLite startup summaries by machineName first, then fall back to cardinality pairing (one unmatched item + one unmatched startup) for the common single-instance case. - Any KuduLite entries still unmatched surface under a new orphanStartups bucket in the payload; renderer prints them as separate 'Instance X Startup Summary (no matching ARM instance)' cards. - When ARM's machineName and SCM's InstanceId disagree, per-instance header shows 'Instance <machine> Full Status Report (SCM: <scm-id>)'. - _emit_labeled hanging-indent helper wraps long Details / Last Error / Last Error Details / Last Error Timestamp values under the value column. - Switch overview table header + underline to Style.PRIMARY; use - * 76 separators around instance headers; upgrade Hint: label to '▶ Hint:'. - Suppress the 'machine name could not be determined' fallback when we successfully paired via cardinality (inst has a startup even without a machineName). - _help.py: drop ARM /siteStatus implementation detail and reword long-summary to match troubleshoot-config phrasing. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: da04b3ec-d5e4-4ab8-aeea-58dd7010ac84

- Remove duplicate/unused top-level 'import os' and 'import sys' (avoid W0404/W0611). - Remove _log_webapp_status_tip helper and all cross-promotion call sites in create_webapp, webapp_up, and _poll_deployment_runtime_status; the tip suggested 'az webapp status' which is out of scope for this PR and (with the group nesting) would not resolve. - Pin troubleshoot_status api-version to a validated literal ('2024-11-01') instead of reading protected client._config.api_version, so the URL doesn't drift if the SDK bumps its default. - Update mock tests to assert 2024-11-01 URLs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: da04b3ec-d5e4-4ab8-aeea-58dd7010ac84

The 'webapp troubleshoot' group scaffolding is owned by this PR; Azure#33709 (config) will drop its duplicate helps entry. Broaden the group summary from the placeholder 'Troubleshoot a web app.' to something that fits both 'status' and the incoming 'config' subcommand. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: da04b3ec-d5e4-4ab8-aeea-58dd7010ac84

Move the ~340-line report renderer and its 12 helpers out of custom.py into a dedicated module (_troubleshoot_status_report.py) with a single public entry point, render_report(payload). custom.py now lazily imports it only on the --report path. No behavioral change; keeps custom.py review-friendly. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: da04b3ec-d5e4-4ab8-aeea-58dd7010ac84

transform_troubleshoot_status_output imports _format_dt, _most_recent_startup, and _startup_fetch_failed which have moved from custom.py to _troubleshoot_status_report.py. Point the import at the new module so 'az webapp troubleshoot status -o table' stops failing with 'Table output unavailable.' Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: da04b3ec-d5e4-4ab8-aeea-58dd7010ac84

…o table Match the --report view: use _short_id() for the InstanceId column, format LastErrorTimestamp via _format_dt(), and surface the lastErrorDetails field as its own column whenever the LastError columns are shown. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: da04b3ec-d5e4-4ab8-aeea-58dd7010ac84

Any None/empty value in a shown column now renders as '-' so a healthy instance's LastError/LastErrorDetails or a Kudu fetch failure's Succeeded/Failed/Updated are visually distinct from an accidentally blank row. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: da04b3ec-d5e4-4ab8-aeea-58dd7010ac84

Adds a per-instance `Details` column (from `inst.details`) so the table surfaces the same short state description the report shows. When at least one instance reports a visible error, registers an `atexit` callback that writes the recommended follow-up `az webapp log tail` / `az webapp log startup show` commands to stderr AFTER the table has flushed to stdout, matching the --report hint footer. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: da04b3ec-d5e4-4ab8-aeea-58dd7010ac84

Rename Succeeded/Failed/Updated to Succeeded (last 24h) / Failed (last 24h) / Updated (last 24h) so the columns' 24-hour window is obvious without cross-referencing the report. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: da04b3ec-d5e4-4ab8-aeea-58dd7010ac84

The most-recent-attempt timestamp is redundant on the summary table; keep it in --report / structured output. Also drop the now-unused _format_dt / _most_recent_startup imports. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: da04b3ec-d5e4-4ab8-aeea-58dd7010ac84

… cell Removing the Updated column dropped _format_dt from the transformer's import list, but the LastErrorTimestamp cell still calls _format_dt inside the show_errors branch. When any instance reported a visible error, the transformer raised NameError which knack surfaces as the opaque 'Table output unavailable' message. Re-import _format_dt and add a regression test that drives the transformer with an errored instance so this path is covered. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: da04b3ec-d5e4-4ab8-aeea-58dd7010ac84

- surface SCM transport errors via SummaryFetchStatus when requests.get raises - _params.py: grammar Default to -> Defaults to Adds a regression test covering the SCM RequestException path. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: da04b3ec-d5e4-4ab8-aeea-58dd7010ac84

Drop the SCM error details and endpoint URL from the fallback message so the report reads cleanly. The report renderer no longer prefixes with 'Startup summary unavailable:' since the new message is self-describing. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: da04b3ec-d5e4-4ab8-aeea-58dd7010ac84

aamos-company · 2026-07-14T16:21:20Z

    ]) for r in result]


+def transform_troubleshoot_status_output(result):


Example Output:

Last error information available if site it stopped on a worker, hints shown

All sites started, last error columns removed

json

aamos-company · 2026-07-14T16:22:11Z

+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+"""Human-readable report rendering for 'az webapp troubleshoot status --report'.


Examples:

All conditions met

No startup attempts in the last 24 hours

The runtime status is reflecting a startup but I manually deleted the startup logs to show what the output would look like in this case

…n ARM is empty When /siteStatus returns no instances the report now explains that this is normal for a healthy app and links the two standard follow-up commands. If SCM returned startup summaries anyway, still render them under the orphan block instead of bailing early. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: da04b3ec-d5e4-4ab8-aeea-58dd7010ac84

…ic label Use portal-oriented guidance rather than exposing internal ARM/SCM plumbing. Also drop the '(no matching ARM instance)' qualifier from the orphan startup header. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: da04b3ec-d5e4-4ab8-aeea-58dd7010ac84

First push

fc07c2c

Copilot AI review requested due to automatic review settings June 29, 2026 21:23

aamos-company requested review from DanielMicrosoft, NoriZC, Pan-Qi, VeryEarly, YangAn-microsoft, jsntcy, necusjz, teresaritorto, yanzhudd and yonzhan as code owners June 29, 2026 21:23

azure-client-tools-bot-prd Bot added this to the August 2026 (2026-08-04) milestone Jun 29, 2026

Copilot started reviewing on behalf of aamos-company June 29, 2026 21:23 View session

aamos-company marked this pull request as draft June 29, 2026 21:23

microsoft-github-policy-service Bot added the customer-reported Issues that are reported by GitHub users external to the Azure organization. label Jun 29, 2026

aamos-company changed the title ~~Create Troubleshoot Command for Linux~~ [App Service] az webapp troubleshoot: provide latest application startup attempt data Jun 29, 2026

Copilot AI reviewed Jun 29, 2026

View reviewed changes

Comment thread src/azure-cli/azure/cli/command_modules/appservice/custom.py Outdated

Comment thread src/azure-cli/azure/cli/command_modules/appservice/custom.py

for item in runtime_items:

_fetch_startup_summary(item)

# --- 3. Assemble payload ---

yonzhan assigned yanzhudd Jun 30, 2026

copilot review updates

cdf2154

aamos-company changed the title ~~[App Service] az webapp troubleshoot: provide latest application startup attempt data~~ [App Service] az webapp troubleshoot status: provide latest application startup attempt data Jul 1, 2026

aamos-company added 4 commits July 1, 2026 11:29

updates based on json field change

fd869fa

fix table output, update based on kudu changes

1d72839

account for app setting disabled

1a0923b

handle non 2xx response from scm

2cab180

aamos-company and others added 14 commits July 10, 2026 09:25

startup summary: print '-' when most recent success/failure is null

3d7add7

aamos-company commented Jul 14, 2026

View reviewed changes

aamos-company and others added 2 commits July 14, 2026 10:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[App Service] `az webapp troubleshoot status`: provide latest application startup attempt data#33673

[App Service] `az webapp troubleshoot status`: provide latest application startup attempt data#33673
aamos-company wants to merge 22 commits into
Azure:devfrom
aamos-company:developer/amberamos/troubleshootcommand

aamos-company commented Jun 29, 2026 •

edited

Loading

Uh oh!

azure-client-tools-bot-prd Bot commented Jun 29, 2026

Uh oh!

azure-client-tools-bot-prd Bot commented Jun 29, 2026

Uh oh!

azure-client-tools-bot-prd Bot commented Jun 29, 2026

Uh oh!

microsoft-github-policy-service Bot commented Jun 29, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

yonzhan commented Jun 30, 2026

Uh oh!

aamos-company Jul 14, 2026

Uh oh!

aamos-company Jul 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		]) for r in result]


		def transform_troubleshoot_status_output(result):

Uh oh!

Conversation

aamos-company commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related command

Description

az webapp troubleshoot status

Data sources

What it surfaces

Testing Guide Images attached in the comments

Uh oh!

azure-client-tools-bot-prd Bot commented Jun 29, 2026

Uh oh!

azure-client-tools-bot-prd Bot commented Jun 29, 2026

Uh oh!

azure-client-tools-bot-prd Bot commented Jun 29, 2026

Uh oh!

microsoft-github-policy-service Bot commented Jun 29, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

yonzhan commented Jun 30, 2026

Uh oh!

aamos-company Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

aamos-company Jul 14, 2026

Choose a reason for hiding this comment

All conditions met

No startup attempts in the last 24 hours

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

aamos-company commented Jun 29, 2026 •

edited

Loading

`az webapp troubleshoot status`

Testing Guide
Images attached in the comments