# Chapter Review: 6.0 - The Waiting Game **Purpose**: To introduce the concept of "Wait Events" and the crucial distinction between "Execution" (CPU work) and "Waiting" (contention/IO) as the two components of performance. **Target reader at this point**: A user who has learned how to read query plans but is seeing a gap between the plan's complexity and actual wall-clock time. **Main takeaway**: Performance = Execution + Waiting. If you aren't using CPU, you are likely waiting for a resource. ## What works - **The Core Metaphor**: The "invisible stopwatch" for wait events is a perfect conceptual bridge. - **The Two Modes of Misery**: Categorizing performance issues into "The Sweat" (CPU) and "The Sigh" (IO) is highly intuitive and memorable. - **Motivating Problem**: Starting with the "missing seconds" in `EXPLAIN ANALYZE` immediately grounds the theory in a common user pain point. ## Technical concerns - **Metric Nuance**: (Minor) The text implies `EXPLAIN ANALYZE` "Execution Time" doesn't include wait time. Actually, wall-clock execution time *does* include it, but the total of node-level costs might not match. The distinction is that `EXPLAIN` tells you *where* in the plan time went, while wait events tell you *why* the process was paused. - **LWLocks**: (Minor) Introduced very briefly on line 75 without much context compared to standard Locks. ## Narrative concerns - **Editing Artifacts**: There are two visible "drafting" errors that break the narrative flow: - Line 31: "...friction of the service shiftfield." (Looks like a merge of "shift" and "field"). - Line 75: "Other times, the friction is The CPU is practically asleep..." (A sentence fragment or duplicate thought). ## Readability concerns - **Sentence Parsing**: Line 75 is a bit of a "word salad" due to the editing error mentioned above. - **Consistency**: The transition from "Maitre D's Service Receipt" to "Building's Heat Record" for `top/htop` is clever but might need a clearer label to ensure readers realize we're switching from Postgres-internal to OS-external tools. ## Highlights/Lowlights - **Most confusing point**: Line 75, where the text seems to double back on itself. - **Most engaging point**: The descriptions of "Sweating" vs "Sighing" elephants. - **Missing example or diagram**: A simple bar chart showing "Execution" vs "Wait" time for a 5-second query would visualize the "missing time" concept perfectly. ## Feedback (Obs/Imp/Sug) ### Observation 1: Double-sentence/Fragment (Line 75) **Observation**: "Other times, the friction is The CPU is practically asleep..." appears to be two sentences mashed together. **Impact**: The reader has to re-read the sentence to make sense of the grammar, breaking the "flow" state. **Suggestion**: Clean up the grammar. (e.g., "Other times, the friction is almost silent; the CPU is practically asleep...") ### Observation 2: Typos (Line 31) **Observation**: "service shiftfield" **Impact**: Minor polish issue; looks unprofessional. **Suggestion**: Change to "service shift." ## Top Revisions 1. **Fix grammatical artifacts** in lines 31 and 75. 2. **Clarify `EXPLAIN ANALYZE` relationship**: Briefly note that total execution time *includes* waiting, but wait events explain the "ghost time" not attributed to active plan nodes. 3. **Explicitly label OS tools**: Ensure the "Building's Heat Record" metaphor clearly maps to `htop/top` for the reader. ## Overall verdict **Promising but needs revision** (due to the editing artifacts and minor technical phrasing). ## Scoring Rubric - **Technical correctness**: 4/5 - **Conceptual structure**: 5/5 - **Narrative flow**: 4/5 - **Readability**: 3/5 (docked for artifacts) - **Example quality**: 4/5 - **Audience fit**: 5/5