Consumer-Driven Evolution: Telemetry Before Breakage

Every evolution decision in this module bottoms out in the same question: *who still depends on the thing we want to change?* Removing Fields Without Removing Consumers needs readers per field; Deprecation as a Process, Not a Label needs a burn-down per surface; Versioning: What a Version Even Promises sunsets need consumers per version; Enum Evolution: The New Value That Broke Old Clients needs to know which SDK vintages will meet the new value. Teams without attribution answer these with grep, memory and hope. Teams with it answer in a dashboard, and the difference shows up as incident count.

The canonical scenario: the team wants to drop a legacy response block that "nobody uses anymore". The query says: web — zero reads for six months; partners — two keys, both migrated last quarter; mobile — 12% of the active fleet is on builds ≤ v4.1, which render this block on the profile screen. Twelve percent of a million monthly users is 120,000 people whose app breaks. The block is not removable — not this quarter — and no amount of engineering opinion in a meeting could have produced that answer. What it *is* is a plan: the number, per build version, becomes the burn-down that tells you which quarter the removal lands.

Attribution is three joins. Identity: every request must carry who is calling — API key, OAuth client id, service identity, and for first-party apps a build/SDK version header — which is an argument for per-consumer credentials long before any analytics need (see API Ownership and the Catalog and API Keys: Identity for Applications). Element: which contract surface the request touched — endpoint and version come free from routing; request fields and enum values sent are visible in the payload; *response-field reads* are the famously hard part, approximated by SDK version, measured exactly only with field selection or instrumented SDKs (see Removing Fields Without Removing Consumers for that ladder). Time: trends matter more than totals — a field at 100 reads/day and falling 20% weekly is a migration finishing itself; the same field flat for a year is a permanent dependency.

Two engineering notes keep this honest. Sample the expensive parts — payload-level attribution on 1% of traffic answers "who sends this field" with plenty of confidence at 1% of the cost, though rare-but-critical consumers (the quarterly job) can hide below sample floors, so keep unsampled counters for identity × endpoint at least. And keep cardinality bounded: attribute to *registered consumers* (hundreds), never to end users (millions) — this is the same discipline as API Metrics: Rate, Errors, Duration, Sizes, applied to evolution data. What you must not do is log payloads wholesale to figure usage out later: that turns an analytics need into a data-retention and secrets liability (see API Logging Without Leaking).

Telemetry informs the decision; it does not make it. Raw counts need weighting: 10,000 reads/day from one partner's retry-happy integration is less important than 10 reads/day from the endpoint your largest customer's billing depends on. The practical form is a gate written into each evolution plan — *removable when: zero reads over one business cycle, or all remaining readers individually contacted and dispositioned* — with disposition meaning migrated, exempted, or consciously accepted as breakage by someone with authority to accept it (see Deprecation as a Process, Not a Label for the endgame options).

Two failure modes deserve names. Threshold gaming: "under 1% of traffic" sounds like a removal gate but 1% of a big API is thousands of daily calls with humans behind them — gates should be zero-or-named, not percentage-fig-leaves. Survivorship blindness: telemetry only sees consumers who are still calling; the integration that broke last month and silently fell back to a manual process is invisible in current traffic but very much a dependency. Attribution is necessary, not sufficient — it tells you who to talk to, and the talking is still part of the process.