The Cartographer's Compass and The Diver's Lead: On the Contrasting Depths of External and Internal Checks
We spend our days drawing maps of our systems, tracing the coastlines of their functionality and charting the deep waters of their performance. In this work, we rely on two distinct instruments, each with its own perspective and purpose. One is the cartographer's compass, taking bearings from a distant vantage point. The other is the diver's lead, lowered directly into the depths to feel the seabed. In our world, these are external pings and internal health checks, and the maps they draw are vastly different.
The external check is our compass. It is a synthetic transaction fired from a remote node somewhere on the globe, measuring the time it takes to complete a journey to our service's front door and back. It tells us what our users actually experience: the total latency of a network hop, a DNS lookup, a TLS handshake, and a server response. It confirms the fundamental truth that the world can indeed reach us. This is the map of the explorer, showing the continent is present and its general shape is correct. But it cannot tell you about the quality of the soil, the health of the forests, or the stability of the cliffs from within.
Conversely, the internal health check is the diver's lead. It is deployed within the service itself, a dedicated endpoint that probes the intricate internals: database connection pools, cache warmth, internal state machines, or the availability of a critical third-party library. It whispers the service's secrets, reporting that while its front door is open, its heart is struggling to beat. It measures not the user's journey, but the service's own vital signs.
This creates a fascinating tension. A service can report perfect internal health—its database connections are lush, its memory heap is pristine—while the cartographer's compass spins wildly, unable to get a fix because a misconfigured load balancer or a network partition is blocking all external traffic. Conversely, an external ping can return a swift, successful 200 OK, painting a green light on a dashboard, while the diver's lead reveals a bed of quicksand underneath: a creeping memory leak or a corrupted cache that has yet to bubble to the surface.
The art, then, is not in choosing one instrument over the other, but in understanding the unique story each one tells. The compass assures us the world can see our lighthouse. The lead line assures us the foundation beneath it is solid. One charts the approach; the other sounds the depths. A reliable service requires both maps, read side-by-side, to navigate safely between the Scylla of external unavailability and the Charybdis of internal decay. We must be both cartographers, surveying from afar, and divers, knowing the truth that lies beneath the waves.
Notes & further reading
A few pages I came back to while writing this: