What does threading.enumerate() return, and what does it tell you about a process that has gone quiet?

## What the call returns `threading.enumerate()` returns a plain `list` of `threading.Thread` objects that are **alive at the instant of the call** — meaning `start()` has been called and the target has not yet returned. Three groups of objects show up in it: - the **main thread**, which you can also get directly with `threading.main_thread()`; - every thread you started with `threading.Thread(...).start()`, including the ones a `concurrent.futures.ThreadPoolExecutor` creates for you; - a **stand-in object** for any thread that was created outside the `threading` module — by native code in a compiled extension, say — and then called into Python. The `threading` module fabricates a limited `Thread` object for such a thread so it has a name and an identity; it cannot be joined and it is always reported as a daemon. Two groups are **absent**: a `Thread` you constructed but never started, and a thread whose target has already returned. That asymmetry is the whole diagnostic value of the call — the list is a census of what is still running, not a history of what ran. ## The fields worth reading ```python for t in threading.enumerate(): print(t.name, t.ident, t.native_id, t.daemon, t.is_alive()) ``` - **`name`** is whatever you passed to the constructor, or an auto-generated `Thread-N`. Naming your workers is not cosmetic: on CPython 3.14 a `faulthandler` stack dump prints the thread name in brackets next to its id, so an unnamed pool produces a dump you cannot map back to a role. - **`ident`** is the interpreter-level identifier. It is the key used by `sys._current_frames()`, which is how you attach a name to a stack in a dump. It is recycled after a thread exits, so it is only meaningful for a live thread. - **`native_id`** (available since Python 3.8) is the identifier the operating system assigns. This is the one that matches what per-thread OS tooling shows, so it is the join key between a Python-side view and a system-side view of CPU time. - **`daemon`** tells you whether the interpreter will wait for this thread at shutdown. A pool of daemon workers that is wedged will not stop the process from exiting; a wedged non-daemon thread will hang shutdown after the main thread returns. - **`is_alive()`** re-checks liveness, which matters because the list itself is a snapshot. ## Why it is step one when a process stops making progress Inventory before diagnosis. Suppose a service is supposed to run eight render workers plus a feeder. The enumeration answers, in one call, which of three very different situations you are in: - **Fewer threads than expected.** Workers have died. In Python a thread that raises out of its target does not take the process down; it prints through `threading.excepthook` and disappears. If that output was swallowed by a logging setup, the only visible symptom is a shrinking thread list and a queue that stops draining. - **The expected number of threads.** Everything is alive and nothing is progressing — the interesting case, and the one that needs a stack dump. - **Far more threads than expected.** Threads are being created per unit of work and never finishing, so each new item adds a thread instead of reusing one. A thread count that climbs monotonically is a leak signature in its own right, and each thread costs its stack allocation. ## What it cannot tell you Alive is not the same as progressing. `threading.enumerate()` has no idea what bytecode any thread is executing, what lock it wants, or how long it has been there. To answer that you need the frames: either `sys._current_frames()` from inside a healthy interpreter, or a signal-triggered `faulthandler` dump of all threads from outside. The usual pattern is to combine them — enumerate to get `ident`-to-`name` mapping, then read the frames keyed by `ident`. ## Snapshot semantics The list is built while the module's internal bookkeeping is held, so it is internally consistent, but it is stale the moment you have it: threads can start and finish while you iterate. Do not treat a count taken once as a measurement — sample it a few times. Holding the returned list keeps those `Thread` objects alive, which is cheap; the objects are small bookkeeping wrappers, not the thread stacks themselves.