Files
obsidian-vault/work/projects/cpm-permanent-breakage-metric-tech-design-2026-11-10.md
T

4.1 KiB

tags, updated, status
tags updated status
work
cpm
tech-design
pixel
2026-11-11 draft

TD: Pixel Definition: CPM Permanent Breakage Metric (macOS/iOS)

Author: Alex M Reviewer: TBD (previous CPM pixel designs: Michal) Stakeholders: Michal, Konrad, Russell (from the previous Tech Designs; confirm) Project: CPM: root-cause the stuck embedded extension messaging (macOS/iOS) Task: to create ("Permanent breakage metrics") Previous Tech Designs: CPM breakage pixels, CPM failure diagnostics Privacy Triage: to request (new pixel names)

Background & Requirements

The goal is permanent CPM failures below 1% of DAU, but no pixel measures it: the number comes from web_extension_cpm_episode through a long query, and the episode is a poor basis. A four-second navigation timer opens it (on iOS 7.244, 6.0% of episodes closed with a late answer on the same page, 42% of those after 30 s), and an open episode is lost when the app exits.

Requirements: no navigation timer, a rate against DAU, no URLs, page content or persistent identifiers.

Problem Statement

Report the tabs whose pages never hear from the extension, and tell one broken page from a broken extension.

While a page initializes, the extension sends the app a message from that tab. A tab is silent when it loaded a page that should get a message and heard nothing for 30 s of app time. A late message still counts as an answer. There is no timer: the check runs when another event arrives (page load, tab close, message, app to background or wake).

  • Pages that count: http(s), extension loaded, not an error page, not a back/forward restore, not a restored session. Suspended time is not counted. A page replaced or closed within 30 s is not reported.
  • A message carries the extension's tab number and the page URL. The app learns which tab it is from the first message that matches exactly one open page (host and path). A message it cannot place answers every tab it could belong to: the metric prefers missing a breakage to reporting a working tab.
Pixel Trigger Frequency
web_extension_cpm_breakage A tab is silent. Parameter tabs: one (no other tab was silent since the extension last answered: likely the page) or many (another tab was too: likely the extension). Daily + count
web_extension_cpm_breakage_persistent A second tab is silent and the extension answered nothing in between. Once per series. Daily + count

Success metric: installs with the persistent pixel / DAU. The episode pixel, web_extension_cpm_background_load_restart and web_extension_cpm_network_process_recovery_applied are removed with the code that only fed them; the recoveries themselves stay.

Pros and Cons

  • Pros: no timer, a slow answer is not a failure, a rate straight from the pixel.
  • Cons: a silent tab left open until exit is not reported (iOS reports it on going to the background); pages left within 30 s are never reported; tabs on the same host and path hide each other; the tab mapping is a heuristic and rarely blames a working extension; one tab alone never triggers the persistent pixel.

Testing

Unit tests for each rule, pixel definition validators, adapter tests, app-hosted macOS and iOS tests. Not done: a real-WebKit run, and a check that the extension messages on every eligible page (search results, duck.ai, non-document types).

Additional Considerations

Privacy: two new pixel names, one enumerated parameter, no URLs or identifiers. Privacy Triage not requested yet. Security: no new private WebKit selectors. Site Breakage: none. Experimentation: none. Operational: a stack of PRs (#8054 removal on top of #8025, then the metric). The removal and the metric ship in the same release. No expiry date: permanent metric. Localization: none.