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

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

You can increment counters using mw.track. These counters are stored via StatsV, and will be publicly visible in a dashboard (see #Viewing data).

Prometheus

Gadgets metrics in Prometheus must start with the mediawiki_gadget_ prefix, followed by your gadget's name (e.g. "test").
The complete metric name may only contain a-z, 0-9, and underscore characters. If other characters are included, this prints an error to the console.
The "gadget name" part must not include, because the first part after mediawiki_gadget_ is used to group metrics belonging to the same gadget.
Counters must end with the _total suffix.
See also Manual:Stats#Recommendations for best practices in (optional) key-value labels.
The (optional) key-value labels may only contain a-z, 0-9, and underscore characters. If other characters are included, this prints an error to the console.

Simple example:

$button.on( 'click', function () {
    mw.track( 'stats.mediawiki_gadget_test_total' );
} );

Example with a label:

$hello.on( 'click', function () {
    mw.track( 'stats.mediawiki_gadget_test_click_total', 1, { action: 'hello' } );
} );
$goodbye.on( 'click', function () {
    mw.track( 'stats.mediawiki_gadget_test_click_total', 1, { action: 'goodbye' } );
} );

Example with a variable label:

var wiki = mw.config.get('wgDBname');
$hello.on( 'click', function () {
    mw.track( 'stats.mediawiki_gadget_test_wikiclick_total', 1, { wiki: wiki, action: 'hello' } );
} );
$goodbye.on( 'click', function () {
    mw.track( 'stats.mediawiki_gadget_test_wikiclick_total', 1, { wiki: wiki, action: 'goodbye' } );
} );

Graphite

Gadgets metrics in Graphite should follow this naming convention:

counter.gadget_$gadgetName.$metricName

The gadget_ prefix must be followed by your gadget's name, one dot, and then the name of your 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.

$button.on( 'click', function () {
    mw.track( 'counter.gadget_test.metric_1', 1 );
    // Do the button thing
} );

How it works

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.

Examples:

Viewing data

The Gadget stats - Grafana dashboard is available to view these counters described above.

In the top-left corner of the dashoard, select your gadget and metric. The data may take a few minutes to appear after you first use a new metric.