A team's dashboard shows an endpoint at 99.98% uptime, low error rate, and healthy latency, and someone proposes removing an optional field nobody seems to reference in the codebase anymore. The dashboard is telling the truth and answering the wrong question. Uptime, error rate, and latency describe whether the service is healthy — they say absolutely nothing about which fields a consumer's code actually reads, which optional expansions get requested, or whether the one enterprise partner generating a tiny fraction of total traffic depends on exactly the thing about to be removed. Service health and contract usage are two different questions, answered by two different kinds of instrumentation, and most teams only build the first one.
Every deferral this course has made to "check your usage data first" — whether a deprecated field is actually safe to remove, whether a documented compatibility tolerance is being honored, whether an expensive expansion is worth supporting — depends on this second kind of instrumentation existing and being trustworthy. Without it, those decisions aren't informed; they're guesses dressed up as engineering judgment, and the guess is usually "probably nobody uses this," which is unfalsifiable right up until the moment it's proven wrong by a broken integration.
Get this wrong and the failure mode is specific and recurring: a team removes something it assumed was unused, based on nothing more than intuition or a quick codebase search of their own client, and breaks a consumer they never knew existed, because the actual evidence — who calls what, how often, from where — was never being captured in the first place. This lesson is about building the specific, narrow instrumentation that turns "probably nobody uses this" into an answer you can actually stand behind.
Analogy🏏Cricket
🏏 Think of it like cricket: A stadium's broadcast engineering team monitors one thing obsessively during a match — is the floodlight system operational, is the camera feed stable, is the graphics overlay rendering without glitches — a genuine, important, continuously watched health signal. A completely separate team, the broadcaster's content analysts, tracks a different question entirely: which specific deliveries, which specific replays, which specific camera angles do viewers actually rewatch, pause on, or seek back to. A broadcast can be running with flawless technical health — every light on, every feed stable — while the content team's separate tracking reveals that almost nobody rewatches the tactical field-placement graphic the production invests heavily in, or that a huge share of viewers specifically rewind to see a contentious boundary-rope decision the technical team never singled out as noteworthy. Neither team's data substitutes for the other's: perfect technical uptime says nothing about which content actually matters to the audience, and audience engagement data says nothing about whether the floodlights are about to fail. Just as broadcast health monitoring and content engagement tracking are two separate systems answering two separate questions, service health monitoring and API usage analytics are two separate systems answering two separate questions about the same API. Just as a broadcaster deciding whether to keep investing in a specific graphic needs the engagement data, not the uptime report, a team deciding whether to remove a field needs usage data, not a health dashboard. The insight is that operational health and actual usage are independent facts, and a decision that depends on usage cannot be answered by a system built only to answer health.
🏏 Showing the Cricket analogy — a Cricket version isn’t available for this concept yet.