[AppService] az webapp log startup: Add commands to list and view Linux container startup logs

[faditawfik21]

Description

Adds new az webapp log startup list and az webapp log startup show commands (preview) that retrieve container startup logs from the KuduLite /api/startuplogs endpoint for Linux web apps.

Commands

• az webapp log startup list — List startup log files with metadata (date, instance, outcome, size)
• az webapp log startup show — Show the latest/most relevant startup log (prefers failures)
• az webapp log startup show --filename <f> — Show a specific log file by name

Features

• Command group marked is_preview=True during server-side rollout
• Graceful 404 handling for regions where the platform hasn't rolled out yet
• Startup log hints added to az webapp up/az webapp deploy on RuntimeFailed or timeout
• 13 unit tests covering all command paths + 2 hint tests

Testing

• 42/42 unit tests pass (azdev test appservice --no-exitfirst)
• 100/100 E2E tests pass against private stamp + EUAP
• azdev style appservice clean

Fixes AB#37627870

[azure-client-tools-bot-prd]

Validation for Azure CLI Full Test Starting...

Thanks for your contribution!

[azure-client-tools-bot-prd]

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

[azure-client-tools-bot-prd]

Validation for Breaking Change Starting...

Thanks for your contribution!

[yonzhan]

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

[github-actions]

The git hooks are available for azure-cli and azure-cli-extensions repos. They could help you run required checks before creating the PR.

Please sync the latest code with latest dev branch (for azure-cli) or main branch (for azure-cli-extensions).
After that please run the following commands to enable git hooks:

pip install azdev --upgrade
azdev setup -c <your azure-cli repo path> -r <your azure-cli-extensions repo path>

[Copilot]

Pull request overview

Adds new preview commands under az webapp log startup to retrieve Linux container startup logs from the KuduLite /api/startuplogs endpoint, and surfaces a troubleshooting hint when deployments fail to start.

Changes:

• Added az webapp log startup list and az webapp log startup show (preview) command registrations + args/help.
• Implemented list_startup_logs and show_startup_log in appservice/custom.py with graceful 404 handling.
• Appended a “TIP” hint to deployment runtime failure/timeout errors pointing users to az webapp log startup show.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/azure-cli/azure/cli/command_modules/appservice/custom.py	Implements startup log retrieval and adds deployment error hints.
src/azure-cli/azure/cli/command_modules/appservice/commands.py	Registers the new webapp log startup preview command group and commands.
src/azure-cli/azure/cli/command_modules/appservice/_params.py	Adds parameters for startup list/show (slot/outcome/instance/filename).
src/azure-cli/azure/cli/command_modules/appservice/_help.py	Adds help entries and examples for the new commands.
src/azure-cli/azure/cli/command_modules/appservice/tests/latest/test_webapp_commands_thru_mock.py	Adds mocked unit tests for list/show behavior and the new error hint text.

---

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

[glaming1]

I think one thing which is very important here is discoverability, for both humans and agents. Here are some ideas from copilot to think about here. One idea would be to create a failing test site and see how you/your agent does at finding the logs without any prompting. You would ideally want to configure your test site to not enable container logs to the filesystem so that without accessing startup logs, they would be blind.

For humans:

1. az webapp log show output — when someone runs the existing az webapp log show (diagnostic settings), add a note or hint that startup logs exist separately. Most users will try az webapp log first and never discover the startup subgroup.
2. az webapp log tail fallback — when streaming logs fails or shows container crash output, a hint to az webapp log
   startup show would be contextually perfect.

For AI agents: 4. Richer --help long-summary — agents discover commands via az webapp log startup --help. The current
description says "Manage web app container startup logs" — consider adding keywords agents search for: "container crash",
"cold start failure", "app not starting", "port not responding". Agents match on these terms when users describe symptoms.
5. Error message breadcrumbs — the TIP hint is great for agents too, since they parse CLI error output. Consider also
adding it to 502/503 error scenarios if the CLI surfaces those anywhere. 6. az webapp troubleshoot-style alias — not
necessarily in this PR, but a future az webapp diagnose or az webapp troubleshoot that aggregates startup logs + deployment
logs + app settings would be extremely agent-friendly. Agents struggle with "which of 5 log commands do I run?"

Concrete suggestion for this PR

The cheapest high-value addition would be enriching the help text for agent discoverability:

helps['webapp log startup'] = """
type: group
short-summary: View web app container startup logs.
long-summary: >
View startup logs written during container initialization for Linux web apps.
Use when a container fails to start, crashes on cold start, times out waiting
for a port, or returns HTTP 502/503 errors after deployment. These logs contain
platform lifecycle events and container stdout/stderr output.
"""

The extra symptom keywords (fails to start, crashes, times out, 502/503) make it much more likely an agent will find this
command when a user describes a problem in natural language rather than asking for "startup logs" specifically.

[glaming1]

Another copilot-assisted comment/something to look into:
HISTORY.rst entry missing — Please add an entry under App Service in src/azure-cli/HISTORY.rst for the two new
commands (see existing entries for the format).

[faditawfik21]

Another copilot-assisted comment/something to look into: HISTORY.rst entry missing — Please add an entry under App Service in src/azure-cli/HISTORY.rst for the two new commands (see existing entries for the format).

It seems like the HISTORY.rst file gets automatically updated every release by the Azure CLI Bot, so there is no need to change anything.

[aamos-company]

Is this being recommended for all app types? This is currently only available for Linux so want to make sure it's not also being presented for Windows

[glaming1]

Good call out!

[faditawfik21]

Good question. This is already scoped to Linux only. The _poll_deployment_runtime_status function is only reachable from the Linux code path. The caller gates on is_linux_webapp(app) at line ~8510, so Windows apps and slot deployments go through _check_zip_deployment_status instead, which doesn't include the hint.

[aamos-company]

Is there any way to reduce the duplication here. IE the prefix of the commands webapp log startup have name, resource, and slot in common. This is a nit so if there is not a clean way to do this, that's ok

[faditawfik21]

Good call. Refactored to define name, resource_group, slot, and instance once under a parent argument_context('webapp log startup') block. The child contexts now only define their unique params (outcome for list, filename for show).

[aamos-company]

Should the show also have an instance param? Currently, if a customer is running on 3+ worker, what is considered the "lastest log"? Sometimes the application fails on one specific worker, so if I were a customer I would want to see the latest on the failing worker v. the successful worker for comparison

[faditawfik21]

Great suggestion. Added --instance to the show command. The KuduLite StartupLogsController already supports ?latest=true&instance=X (the instance param is accepted independently alongside latest), so /api/startuplogs?latest=true&instance=lw0sdlwk000002 returns the most recent log for that specific worker. Also added a unit test and a help example for it.