# Production guide — Diagnose an AppEngine request

Companion to [the full course](../appengine-operate-and-extend-the-platform.md). This package supplies live documentation captures, real response transcripts and source excerpts. It does not include a finished video or a deployed software fix.

## Open on the contradiction

Begin with the actual profile response: PUT returned 200 with no body, while the fresh GET still had no phone. Say: “The request completed. The promised change did not. Let's follow it to the code.” The film's useful result is a precise diagnosis and a release test, not a fictional repair.

Then show the route through five labeled stages: request, identity, controller, service, record. Use a simple diagram based on the course. A source excerpt is code evidence; do not dress it as a screenshot of a fixed application.

## Scene plan

| Scene | Asset or source | Learning objective |
| --- | --- | --- |
| The symptom | `appengine-client/06-update-and-retry.png` | Status and persisted outcome differ |
| Runtime reference | `appengine-operations/01-runtime-api-index.png` | Find the API served by the installation under investigation |
| Narrow search | `02-profile-route-search.png` | GET and PUT are separate operations |
| Response contract | `profile-route-detail.json` | Declared success is an implementation promise to test |
| Reproduce | Course curl sequence and client evidence | Same customer, organization and field before/after |
| Follow code | Controller delegation and empty service body | Identify the missing persistence operation |
| Health comparison | `03-health-comparison.png` and both JSON responses | Read nested component health, not just the headline |
| Queue correlation | Background-jobs course evidence | Record, job and business effect are separate stages |
| Environment diagnosis | Vibe environment readback | Saved project and running container are separate facts |
| Release acceptance | Course case table | Verify ownership, validation, persistence and errors |

The operations stills are in [the assets directory](../assets/appengine-operations). The reused profile transcript is directly relevant evidence from the companion connected-client rehearsal. Do not substitute unrelated clips of successful saves.

## Capture the request safely and accurately

Use the same installation for the before read, attempted update and after read. Show its version and a short environment label without displaying credentials. If filming a fresh rehearsal, use a fictional customer controlled by the recording team. Do not change a real customer's contact information for a demonstration.

Keep bearer values hidden. The documentation page can store entered credentials locally; use its Forget all control after a recording on a shared machine. For request footage, show method, path, status and selected response fields. Avoid a Network pane that displays authorization headers or unrelated traffic.

Hold the empty response body long enough to explain why a blind `response.json()` fails. Then show that the after read still lacks the phone. Only after those observations should the film open the service source. This sequence teaches investigation: observe, narrow, explain.

When showing the source, retain enough surrounding context to identify `updateClientProfile`. Highlight the commented-out line as inactive code. Do not narrate “uncomment this and it is fixed.” The target identity is a customer, and a safe implementation needs field validation and ownership enforcement. No software patch was part of this documentation rehearsal.

## Make the operating signals legible

The full health transcript can extend below one viewport. Use a readable crop of the two relevant facts: `/health` reports KeyDB up, while monitoring's nested Redis status is unhealthy despite a healthy headline. Keep endpoint labels attached to each result. Both requests were observed; the cause of their disagreement was not established. Do not invent a Redis outage or claim a confirmed monitoring fix.

For queues, use the sanitized aggregate evidence or the jobs course's own matching training job. A shared queue may contain other organizations' work. Do not browse unrelated payloads or trigger pause/resume/remove actions to create dramatic footage. Explain that a healthy process can still contain failed work and that an empty UI Runs tab did not reflect the API history in the rehearsal.

Usage figures describe telemetry. They must not become a paid-plan warning or a claim that a particular message was delivered. If totals appear, disclose pagination and the snapshot time.

For Vibe, present the environment readback beside the current editor: AppEngine record exists, container status reports a missing domain, files are accessible through another service. The older missing-key message is historical; the fresh get-spinforge request returned 200. Never expose the full hosting response if it includes connection details.

## The release chapter

Use the acceptance-case table as an on-screen checklist with narration. The essential cases are allowed-field persistence, validation, missing/expired auth, another customer's identity and storage failure. Explain that a readback after save is necessary but does not replace the ownership test.

The isolated-development section is a maintainer procedure. Label it accordingly. Do not imply that the recording team installed a new server, changed the source, rebuilt production or verified rollback. The previous topic promised all of those without evidence; the completed manuscript deliberately describes the work still required for an engineering release.

A rollback visual should show a known prior artifact and compatible configuration/data. Rebuilding the current working tree is not inherently a rollback. Likewise, changing a port is not enough to isolate a database or queue.

## Before publishing

Re-run the profile sequence against the release being filmed. If the no-op is fixed, replace both the response and source chapter with the newly observed behavior; do not reuse the old failure as if it remains current. Recheck the health disagreement, public monitoring access and environment status. Keep any unresolved limitation in the narration beside the relevant step.

Verify all source paths and UI labels. Ensure screenshots and terminal output contain no passwords, bearer values, session invitations or unrelated records. Include captions for the exact error strings and endpoint methods. End with the learner's useful artifact: a concise incident report and a specific acceptance test that a reviewer can execute.