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

17 KiB
Raw Blame History

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

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

Internal metrics, keep out of public PRs. Companion: cpm-wake-init-detection-tech-design-2026-11-10 (adds last_stage to the pixel defined here). Where we are: cpm-project-summary-2026-11-03 (section "Состояние на 10 ноября"). Review of the earlier attempt that this design replaces: same section.

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", from the plan in cpm-project-summary-2026-11-03) Previous Tech Designs: cpm-readiness-telemetry-tech-design-2026-10-15, cpm-m3-telemetry-privacy-triage (both describe pixels this design supersedes) Privacy Triage: to request (new pixel names, see Additional Considerations)

Background & Requirements

The project goal is permanent CPM failures below 1% of DAU (0.2–0.5% counts as success). Today that number does not exist as a pixel. It is derived from web_extension_cpm_episode with a long SQL: a four-second navigation timeout opens an episode, a later timeout or reload confirms it, a five-minute deadline or a response closes it. Three problems:

  • The timer measures slowness, not breakage. On iOS 7.244, 6.0% of episodes closed with a late answer on the same page, 42% of those later than 30 s. A page that answers after 40 s is counted as a failure.
  • Episodes are lost. An unfinished episode lives in memory; closing or killing the app drops it. The pages that stay broken longest are the ones that end with the app.
  • The pixel carries what the investigation needed (diagnostic booleans, bg_events, load fields) and is being trimmed to five parameters (PR 2 in the stack below). What remains cannot be turned into a small, fixed dashboard set.

Requirements:

  • A small fixed set of metrics, as rates against DAU, for the health indicators dashboard.
  • Detection that does not depend on a timer and does not depend on reaching a deadline before the app exits.
  • No page content, URLs or persistent identifiers.
  • Runs next to the episode pixel for one release, so the two series can be compared before the old one is removed.

Problem Statement

Define and measure, per platform and version:

  1. Breakage: an http(s) page that finished loading with the extension loaded, and never got the extension's answer while its document lived.
  2. Persistent breakage: several documents in a row with no answer in between, meaning the extension is broken for the user, not for one page.
  3. How many installs per day are affected, and how many breakages happen.

The wake investigation (which init step stops) is separate: cpm-wake-init-detection-tech-design-2026-11-10.

A page is healthy as soon as an answer for its document arrives, at any time while the document lives (a late answer is not a failure). A page that never got the answer is judged when its document ends. There are no navigation timers. The approach is additive: the existing monitor, its timers and the episode pixel stay unchanged; the new logic is a second consumer of the same events.

What was wrong with the first attempt

The first attempt (branch alex/cpm-breakage-pixel, commit e6419bb910) already used page-end judging, but combined it with deleting the episode pixel and had these defects, all addressed below:

  1. Unanswered measurements older than five minutes were dropped, so the longest-silent pages were never reported.
  2. No minimum lifetime: a page left 200 ms after loading counted as broken.
  3. A web content process crash counted as extension breakage.
  4. background was derived from "background load took at least one second" and from one app-wide signal, not from the page's navigation.
  5. Pages alive when the app exits were never judged.
  6. The macOS pixel definition omitted pixelSource and channel and used iOS-only suffixes.
  7. navigationWaitContexts leaked an entry when the context was replaced, and cpmStage parsing had no test.

Detection rules

Per eligible document: http(s), not a browser error page, not a history restore from cache (existing eligibility rules, unchanged).

Event Effect
Navigation finished, extension loaded Document becomes judgeable and its clock starts. If the extension is not loaded yet, it becomes judgeable when the extension loads while the page lives.
Attributed dashboard response (later also response_sent, see the companion design) Healthy. Ends judging for this document. Resets the streak.
Response that cannot be tied to one document The document is not judgeable (neither outcome provable).
Document ends by a new navigation or tab close Judge now.
App suspends (iOS to background, macOS sleep) or macOS terminates Judge every pending judgeable document now, once. The processes still run at this moment; nothing is judged while suspended.
Web content process terminated Not judged. The silence is the crash's, not the extension's. The tab's next navigation is reported with reason=tab_crash.
Extension signals cpmStage = config_unavailable or settings_missing Breakage at once (ended_by=explicit_signal), no lifetime limit.
Extension reload Existing rule: evidence from the replaced context is discarded.

A document is reported only if it lived at least 30 s after it became judgeable (minimum lifetime). A shorter silence is ambiguous: it may be a slow wake. The 30 s value follows WebKit's unload timer and the late-answer data above; it is a constant in the first release. Shorter and longer lifetimes are told apart in analysis by the lifetime parameter.

A judged document is never judged again and never retracted: an answer after the report changes nothing. Documents whose process or app ends without a suspension event (kill, crash of the app) are lost; this is the known bias, now limited to the time between the last suspension and the kill.

Measurement state does not expire after five minutes. The old five-minute lifetime stays only for the restart observation, which is unrelated.

Persistence

The monitor keeps a streak: the number of consecutive judged-broken documents since the last healthy one (any tab). When it reaches 3 the persistent pixel fires once for that streak. A healthy answer resets the streak. The streak lives in memory for the process lifetime. A relaunch resets it (see open questions).

tabs on the persistent pixel records whether the streak's documents were in one tab or several. This keeps the cross-tab distinction the earlier analysis found important (cross-tab permanent was the figure used against the 1% target).

Pixels

Pixel Trigger Frequency
web_extension_cpm_breakage A document is judged broken. Sent at that moment, once per document. Daily + count (dailyAndCount)
web_extension_cpm_breakage_persistent A streak reaches 3 documents. Once per streak. Daily + count (dailyAndCount)

_daily estimates installs per day, _count counts events. Both metadata sets follow the existing episode pixel on each platform: appVersion on both; macOS also pixelSource and channel, suffix daily_count; iOS keeps its existing suffix set. The macOS definition must match what is sent (item 6 above).

web_extension_cpm_breakage parameters:

Parameter Values
reason session_restoration, tab_crash, extension_reload, other. Context of the document's navigation. Same values as the episode pixel.
background woken (the extension's background view was created during this navigation), warm (a background view existed and none was created), unknown (no background view known). Comes from the manager's didCreateBackgroundWebView delegate callback, correlated to the navigation, not from load duration.
ended_by navigation, tab_closed, app_suspended, explicit_signal.
lifetime Time from judgeable to judged: 30s_to_2m, 2m_to_10m, over_10m. Omitted for explicit_signal.
streak Breakages in a row including this one: 1, 2, 3_plus.

web_extension_cpm_breakage_persistent parameters:

Parameter Values
tabs one or many: whether the streak's documents were in one tab or several.

The last_stage parameter for wake diagnosis is added by cpm-wake-init-detection-tech-design-2026-11-10, not here. No URL, document, tab or process identifier is sent.

The metric set for the dashboard

Metric Source Meaning
Installs with persistent breakage / DAU breakage_persistent_daily, split by tabs The success metric (target below 1%).
Installs with any breakage / DAU breakage_daily Upper bound; includes single-page failures.
Breakages per day breakage_count, split by reason, background, ended_by Volume and mix, for diagnosis.

Everything is per platform and app version. Rates use the existing DAU series.

Where it lives in the code

  • CPMMessagingHealthMonitor (existing, per-tab document state already tracks response, judgeable and crash state) gains a per-document record independent of the timeout measurement: when it became judgeable, whether it was judged, the navigation kind. Judging and the streak are small additions to existing handlers; the correlation logic is reused, not duplicated.
  • New event CPMMessagingHealthEvent.backgroundViewCreated, sent by the manager from didCreateBackgroundWebView. It replaces backgroundLoaded(wasWoken:) from the first attempt.
  • macOS also sends the existing suspension event on termination (applicationWillTerminate); iOS and macOS sleep already send interruptionBegan.
  • AutoconsentWebExtensionMessageHandler already separates the cpmStage signals; they get a test.
  • CPMMessagingBreakageReport and the two pixel events in WebExtensionPixelFiring. Definitions in both platforms' web_extensions.json5 and params_dictionary.json5.

PR stack

PR Branch Content State, 10 Nov
1 alex/cpm-episode-metrics, #8025 Remove ineffective recovery fixes, their flags and pixels pushed, in review
2 alex/cpm-pixel-cleanup (f04c93730f) Remove the diagnostics, trim the episode pixel to five parameters. No new pixel, no detection change. Needs the Danger label (existing pixel parameters change). local; 1104 package tests pass, SwiftLint clean on the changed core files; app builds and pixel validation not run; not pushed
3 new, on top of 2 This design: two pixels, document-end judging, streak not started
4 new, on top of 3 Init progress marks, last_stage (cpm-wake-init-detection-tech-design-2026-11-10) plus extension #3727 native part drafted in alex/cpm-init-diagnostics (adb28e643d), needs the same fixes
5 later Remove the episode pixel and its timers and states, one release after PR 3 after comparison

Old branches alex/cpm-breakage-pixel and alex/cpm-init-diagnostics stay as sources only.

Pros

  • Measures the user-facing fact (this page never got an answer), not an elapsed time.
  • A late answer is never a failure, which removes the 6% late-answer error class and its tail.
  • Detected breakages are sent at once, so closing the app loses only documents that were never judged.
  • Persistent breakage has its own daily pixel: the success metric is one series, not a join.
  • Additive: the episode pixel and the recovery logic keep working, so the new numbers can be validated against the old.

Cons

  • Pages that live until a kill are not judged. Persistent breakage that a user never ends (leaves the page open for hours) appears only at suspension.
  • 30 s minimum lifetime hides breakage on short pages. If most breakage is on short pages the metric underestimates; lifetime shows how much sits near the limit.
  • A page-based streak does not equal the old "no answer for five minutes". The two series will differ, and the comparison needs interpretation.
  • The streak resets on relaunch; iOS terminates apps often, so persistent breakage across launches is undercounted.

Risks

  • Pixel volume. A user with persistent breakage fires one count request per page. Mitigation: soft cap of 20 breakage count requests per process; the persistent pixel is unaffected by the cap. Volume to be estimated from web_extension_cpm_episode counts before release.
  • Healthy evidence that is missing in a working page (dashboard refresh not delivered, wrong attribution). Counted as breakage. The earlier analysis found other_tab_response at 37–53% of outcomes, an attribution problem. Mitigation: documents with an unattributable response are not judged, and unknown attribution is visible only locally for now. Compare with the episode series.
  • Judging at suspension assumes silence for 30 s before suspension means breakage. A wake that began just before suspension could be reported. Mitigation: the lifetime limit; the suspension case is separated by ended_by.
  • Simulation switch. The Debug "Simulate CPM Messaging Breakage" switch hides dashboard responses from the monitor and must keep doing so for both detectors.

Testing

  • Unit tests for each rule in the table: late answer before document end is healthy; unanswered document shorter than 30 s is not reported and does not touch the streak; unanswered longer document is reported on navigation, tab close, suspension; process termination is not judged and tags the next navigation; judged once; extension not loaded at finish becomes judgeable on load; unattributable response; explicit signals; streak reaches 3 once, resets on a healthy answer; tabs value; background from the view-created event inside and outside the navigation window; simulation switch hides answers; extension reload evidence.
  • Handler test for cpmStage parsing; test for navigationWaitContexts after a context replacement.
  • Pixel definitions: schema validators of both platforms in CI; parameter lists match what is sent (compare the macOS definition against the event).
  • Manual: updated steps in CPM Breakage Testing Steps (Debug simulation switch: load a page for 35 s without an answer, navigate away, expect one breakage; three in a row, expect persistent).
  • Real WebKit: the CPM repro harness (PR #7378) with the injected error 6 and idle-wake fixtures to see both pixels with the expected values. Not run yet.

Additional Considerations (if applicable)

Privacy

Two new pixel names with enumerated, bucketed parameters. No URLs, page content, tab or document identifiers, or process IDs. The streak is a local integer that is never sent; only streak as a bucket. Because the pixel names are new, Privacy Triage is required before release. Not requested yet. Combined distinguishability of reason, background, ended_by, lifetime, streak and the platform metadata is small (five low-cardinality enums).

Security

No new private WebKit selectors. didCreateBackgroundWebView is already implemented in the manager.

Site Breakage

None intended. The detector only observes events; it sends no messages and changes no recovery behavior. Existing recovery (error-6 restart, network recovery, upgrade before load) is unchanged.

Experimentation

No experiment. The comparison is observational: the new and old series for the same versions during the overlap release.

Operational

  • Overlap: ship PR 3 next to the episode pixel for one release; compare "installs with persistent breakage / DAU" with the existing permanent-failure series by platform. Expected: new is lower where late answers dominated, higher where the episode never reached its deadline. Remove the episode pixel (PR 5) when the difference is explained.
  • Pixel expiry follows the existing definitions (2027-01-15).
  • Add the three metrics to the health indicators dashboard. Data checks use ClickHouse: pixel counts from metrics.pixels_aggregation (pixel_id = 'web'), parameters from metrics._pixels_new (pixel_id = 'web', one day).
  • No remote kill switch is proposed. If volume surprises, the soft cap and the next release are the lever. Question for reviewers: is a feature flag required for a new pixel here?

Localization / Internationalization

None.

Open questions

  1. Minimum lifetime 30 s and streak 3: acceptable as first constants, or tune from the episode data first?
  2. Persist the streak across launches (a local counter)? It makes persistent breakage visible across iOS terminations at the price of local state.
  3. Flag or no flag for a new pixel.
  4. Judge at suspension: accept, or only at document end?
  5. Soft cap value.