⚠️ Heads up: Thanos PagePreviews Data for the week of May 19, 2025 are invalid.
Description:
We need to replace the PagePreviews* metrics currently emitted to Graphite via the legacy statsvTracker system with Prometheus-compatible instrumentation using StatsLib.
Metrics affected:
PagePreviewsApiResponse.sample_rate
PagePreviewsApiResponse.median
PagePreviewsApiFailure.rate
PagePreviewsPreviewShow.sample_rate
PagePreviewsPreviewShow.median
These power dashboards for:
- API performance (response time, failures, rate)
- Preview show rate and time-to-preview (TTP)
- Utilization (e.g., previews shown ÷ API responses)
Current behavior:
Metrics are emitted via statsvTracker, initialized in src/index.js of the Popups extension, and triggered in src/reducers/statsv.js by action types:
FETCH_END
FETCH_FAILED
PREVIEW_SHOW
This path is Graphite-only and will stop working after Graphite is set to read-only on April 30, 2025.
Goal:
Re-instrument these metrics using StatsLib or another Prometheus-compatible system, using metric names that follow Prometheus conventions (snake_case, proper suffixes, etc.).
Example:
` Stats.timer( 'page_previews_api_response_time_seconds' ).observe( durationMs / 1000 ); Stats.counter( 'page_previews_api_failures_total' ).inc(); Stats.timer( 'page_previews_time_to_preview_seconds' ).observe( durationMs / 1000 );
Suggested steps:
Identify all statsvTracker calls in the Popups extension
Replace them with StatsLib-based metrics
Ensure the new metrics are collected
Update Grafana dashboards to use the new Prometheus metrics
Testing instructions
See also T392319#10766865
Docker setup
- Make sure WikimediaEvents, EventLogging, Popups, EventBus are installed.
- Add following to LocalSettings.php
$wgStatsdServer = 'statsd'; $wgStatsFormat = 'dogstatsd'; $wgStatsTarget = 'udp://statsd-exporter:9125'; $wgStatsPrefix = 'mediawiki'; $wgWMEStatsBeaconUri = 'http://localhost:8127/beacon/statsv'; $wgPopupsStatsvSamplingRate = 1; $wgPopupsGateway = 'restbaseHTML'; $wgPopupsRestGatewayEndpoint = 'https://en.wikipedia.org/api/rest_v1/page/summary/';
Edit docker-compose.override.yml and add:
statsd-exporter:
ports:
- "9112:9112"
image: prom/statsd-exporter:v0.22.2
command: "--web.listen-address=:9112"
statsv:
build: ./extensions/WikimediaEvents/devserver/
ports:
- "8127:8127"Launch Statsv beacon service
cd extensions/WikimediaEvents/devserver composer start-statsv
In another terminal window run
watch 'curl -s localhost:9112/metrics| grep Popups'
Check events are firing
mw.track( 'stats.mediawiki_Popups_api_response_seconds', 321 );
Check the watch tab to confirm the event showed up.
Test the patch
- Create a page with a link to [[Barcelona]] and create a Barcelona page so it doesn't show as red link.
- Refresh page and hover over Barcelona link.
- Change tab
- Check event showed up in the start-statsv devserver
Notes
To migrate the metrics, you can refer to the following resources:
- Detailed guidance on the conversion process.
- A video tutorial on the conversion process.
- Slides on best practices for converting metrics to statslib.
Once your metrics are migrated to Prometheus, you can switch the datasource to Thanos for any widget you would like to keep and update the query accordingly.
