Outcome
By the end of this lesson, you will be able to separate a build failure from a runtime failure, read the two log surfaces that tell them apart, and judge when the logs have stopped being evidence.
| Tier | Engineer |
| JTBD | ”Find out why it will not stay up, without four browser tabs.” |
| Personas | Platform Engineer · SRE · Developer |
| Prerequisites | M6.6.L2 |
| Time | 9 minutes |
| Bloom verb | Separate (Analyze), Read (Understand), Judge (Evaluate) |
1. Concept
A bad deploy fails in one of two places, and the fix is different in each.
IT NEVER BUILT the builder printed the reason: a missing dependency, a compile error, a failing test, an out-of-memory kill
IT BUILT AND WILL the replica is printing the reason: a missingNOT STAY UP environment variable, an unreachable database, the wrong portTwo surfaces answer these: the build output, and the running replica’s log. Asking for both at once is the fastest route to the right half.
Logs are windowed, and absence proves nothing
Build output is relayed through the service’s event trail, and that trail is capped. When the window has been reached, older output was never returned at all.
COVERAGE COMPLETE everything recorded was readCOVERAGE WINDOWED older output exists and you did not see itA long or repeatedly retried build is exactly the case most likely to have been pushed out of the window. In that state, a missing line means unknown, not absent. That distinction is the difference between a diagnosis and a guess.
One thing to be careful with
An application can print anything into its own logs, including a credential it read from its environment. Ask for the smallest tail that answers the question, and do not paste log output around more widely than you need to.
2. Demo
YOU "Why did the last deploy of hello-api fail?"
ASSISTANT deploy trail: queued, building, FAILED at build build output: npm ERR! missing script: build coverage: complete
YOU "And the one before it?"
ASSISTANT deploy trail: deployed, rollout never completed replica log: Error: connect ECONNREFUSED 10.0.3.14:5432 coverage: windowed, older output not returnedThe second answer names its own limits, which is what makes it usable.
3. Hands-on (6 min)
1. Break a deploy on purpose in your capstone service: a wrong port, or a missing environment variable.2. Ask your assistant why the deploy failed.3. Read whether the answer came from the build output or the replica.4. Ask for the coverage, and check whether the window was complete.5. Fix it, redeploy, and confirm the trail goes green.Do it through MCP. The same task you just did in the console, asked in one sentence.
BEFORE A service you can safely break, and a deploy that has failed at least once.ASK "Why is this service not staying up? Show me the deploy trail, the build output and the replica log."CHECK whether the answer says its log coverage was complete or windowed. Acting on a windowed answer as though it were complete is how a wrong root cause gets agreed in a meeting.Tools behind it: diagnose_deploy (read, Diagnose), get_build_logs (read, Ship), get_service_logs (read, Ship), get_service_events (read, Diagnose). The full catalogue is at zop.dev/learn/mcp-tools.
4. Knowledge check
Q1
The deploy trail says the build finished and the rollout never completed. Where is the reason?
A. The build output
B. The running replica’s log
C. The audit log
D. The service configuration
Show answer
Correct: B. The build succeeded, so the builder has nothing left to tell you. Something inside the container is refusing to stay up, and it is almost always saying so on its own output.
Q2
Your log answer reports coverage as windowed. What follows?
A. The build printed nothing
B. The service has no logs
C. Older output exists and was not returned, so absence proves nothing
D. You need write access
Show answer
Correct: C. Windowed means the cap was reached. Concluding “the build never printed that error” from a windowed answer is the mistake this lesson exists to prevent, and long retried builds are the most likely to be truncated.
Q3
Why ask for the smallest tail that answers the question?
A. To save money
B. Because an application can print secrets into its own logs and nothing redacts them
C. Because long tails are slower
D. Because the tail is capped anyway
Show answer
Correct: B. A process that read a credential from its environment can log it, and no layer in between can detect that. Asking for less, and quoting less, is the discipline that keeps a debugging session from becoming a disclosure.
5. Apply
Next time a deploy misbehaves, ask one question with all three parts in it: the trail, the build output and the replica log. You will spend the first minute knowing which half of the problem you are in.
KEEP one build failure and one runtime failure, side by side