Gadget kitchen: recording metrics
- Back to Gadget kitchen
Some gadgets are serious business. When your gadget gets serious, you might want to instrument it for analytics purposes, for example to measure the click rate of specific UI elements added to a page by the gadget. This page documents some conventions and resources available for doing this.
(keywords for searching: logging, tracking, instrumentation, telemetry, analytics, metrics, events)
The advice below is written with Wikimedia wikis in mind. Other wiki farms may have different conventions.
Guidelines
[edit]Gadgets and other scripts sending telemetry should follow the WMF data collection guidelines. Since some of the events you send are immediately public (see below), you should also consider data publication guidelines.
In general, do not send any metrics that you wouldn't post on a public wiki page.
Recording events
[edit]You can record counter metrics using mw.track via the counter.gadget_* topic. These metrics will be stored Statsv[1], and will be publicly visible in a dashboard (see #Viewing data).
Gadgets should follow this naming convention:
counter.gadget_$gadgetName.$metricName
The prefix must be followed by your gadget's name, a dot, and the name of the metric. The names must not contain any dots, as this would go to a different public index, and not be compatible with the Gadget Stats dashboard.
The result of calling mw.track() is buffered in the browser tab and sent to the Statsv server in batches. The easiest way to trigger this is to switch to a different browser tab (or open a new new, or minimise the window. Note that metric sending might be blocked by an ad blocker.
$button.on( 'click', function () {
mw.track( 'counter.gadget_test.metric_1' );
// Do the button thing
} );
Examples:
- https://en.wikipedia.org/wiki/User:SD0001/AFC-submit-wizard.js
- https://github.com/wikimedia-gadgets/VariantAlly/blob/c7e431fe9c5dc49362d19c8a4ca0f7885ca93751/gadgets/variant-ally/src/stats.ts#L16
Viewing data
[edit]A dashboard is available offering some simple views into the data logged as described above: https://grafana.wikimedia.org/d/IlK0cZbSk/gadget-stats
In the top-left corner, select your gadget and the metric you wish to view. The data may take a few minutes to appear after you've sent it.