# Chapter 7: The Waiting Game (Diagnostic Guide) Every time the elephant stops moving, he leaves a trail of breadcrumbs explaining *why*. To understand your workload, you must learn to read these signs. ## The Diagnostic Flowchart When your query is slow, look at the "Wait State" in `pg_stat_activity`: ### 1. Is the Elephant Still "Working"? (CPU/No Wait) If there is **no wait event** (or it says "CPU"), the elephant is in "The Sweat" mode. He is currently hammering away at a task in the CPU. - **Top Suspects:** [[Resources/CPU|CPU Frequency]], [[Resources/Memory|Memory sorting]], or [[Extension/_Extension|Extension code]]. ### 2. Is the Elephant Waiting for a Book? (IO Wait) If you see **IO** events, the elephant is in "The Sigh" mode, standing by the elevator to the Frozen Pantry. - **Top Suspects:** [[IO/_IO|Disk Throughput]] or **Memory Pressure**. ### 3. Is the Elephant Bumping into Others? (Lock/LWLock Wait) If you see **Locks**, the elephant is trapped in a crowd at the Narrow Gate. - **Top Suspects:** [[Lock/_Lock|Heavyweight Locks]] or [[LWLock/_LWLock|LWLocks]]. ### 4. Is the Elephant Waiting for a Message? (IPC Wait) If you see **IPC**, the elephant is waiting for his teammates to yell back across the room. - **Top Suspects:** [[IPC/_IPC|Parallel Worker Contention]] or **Message Queue saturation**. ### 5. Is the Elephant Just Bored? (Client/Activity Wait) If you see **Client**, the elephant is just sitting there waiting for *you* to tell him what to do next. --- ## The Wait Event Library - [[Activity/_Activity|Activity]] - Sleeping, idling, or background housekeeping. - [[BufferPin/_BufferPin|BufferPin]] - Waiting for a page to be unpinned (common during Vacuum). - [[Client/_Client|Client]] - Waiting for the network or the application. - [[Extension/_Extension|Extension]] - Custom code from external modules. - [[CPU/_CPU|CPU]] - Internal processing and algorithmic waits (Sweating). - [[IO/_IO|IO]] - Fetching data from the Frozen Pantry (Disk). - [[IPC/_IPC|IPC]] - Parallel worker synchronization. - [[InjectionPoint/_InjectionPoint|InjectionPoint]] - Controlled testing and simulated stalls. - [[Lock/_Lock|Lock]] - Transactional blockades on tables or rows. - [[LWLock/_LWLock|LWLock]] - Microscopic friction in shared memory data structures. - [[Timeout/_Timeout|Timeout]] - Staff members giving up or sleeping (e.g., `pg_sleep`).