Jump to content

Metrics Platform/Local development setup

From Wikitech

This guide describes the steps you need to run a local MediaWiki configured to work with Metrics Platform, either to create/modify/test instruments or work on any client library.

Currently, the JS and PHP Metrics Platform Clients only work within the EventLogging extension, which is part of the Event Platform environment for MediaWiki. Before getting started with Metrics Platform, you need to have an up-to-date MediaWiki development environment. This guide includes instructions for setting up Metrics Platform using MediaWiki Docker, MediaWiki Vagrant, or your local dev environment.

Using MediaWiki Docker

To set up MediaWiki Docker, follow the instructions in DEVELOPERS.md in the root of the mediawiki/core repository.

Once your MediaWiki site is fully installed, you will need to install and configure the components required to work with Metrics Platform:

  • Event Platform: Follow the instructions in the Event Platform section to set up an Event Platform environment alongside your MediaWiki development environment. You will be able to log events to a containerized EventGate instance (herein "EventGate") from both server-side and client-side MediaWiki code. EventGate will validate events against schemas fetched from https://schema.wikimedia.org.
  • Configuring Metrics Platform: Follow the instructions in the Configuring Metrics Platform section to configure streams and launch some sample events using the Metrics Platform API to see them in the local Event Platform you have installed before. That way you will test that everything is working.
  • Install MetricsPlatform extension: Follow the instructions in the Install MetricsPlatform extension section to install this extension and enable experimentation capabilities for Metrics Platform.
  • Install MPIC: Follow the instructions in the Install MPIC section to run MPIC if you want to use this tool to register and manage your instruments/experiments

Configuring Metrics Platform

Here we'll configure some streams in our local MediaWiki site to test the Metrics Platform API to produce sample events. That way we will be able to conclude that our environment is working fine. In the end, Metrics Platform instrument are pieces of code that reside somewhere and end up producing events using one of the following functions we are going to test. In this case we are going to test using the Javascript implementation but we could do something similar for the other implementations (PHP, Java and Swift).

To do that, we'll configure a stream in LocalSettings.php to test some of the functions that are currently available in the Metrics Platform Client Library for Javascript (anyway take a look at the Javascript API to see how to develop an instrument properly using this client library)

Keep in mind that, you can, for example, keep open your events.json file to see how the events are produced while testing all these functions:

tail -f events.json

Add the following configuration to your LocalSettings.php to enable a new stream called my_stream:

$wgEventStreams = [
    // Here are the configuration for all existing streams
    'my_stream' => [
	    'schema_title' => '/analytics/product_metrics/web/base',
	    'destination_event_service' => 'eventgate-analytics-external',
	    'producers' => [
		    'metrics_platform_client' => [
			    'provide_values' => [
				    'performer_is_logged_in',
				    'mediawiki_skin',
			    ],
		    ],
	    ],
    ],
];
$wgEventLoggingStreamNames = array_keys( $wgEventStreams );

Once that done, you should be able to see how an event is produced using the developer console in your browser taking a look at the Network tab. You can use submitClick to submit an action that will be identified as a click or submitInteracion if you want to pass the related action as a parameter.

submitClick

We can produce an event for this new stream with the following code, using only its name:

mw.eventLog.submitClick('my_stream');

submitInteraction

We can produce an event for this new stream with the following code, passing its name, the schema and the action we want to register as parameters:

mw.eventLog.submitInteraction('my_stream',   
   '/analytics/product_metrics/web/base/1.0.0', 'init');

Working with schemas locally

If you are working on creating or updating schemas, you can configure MediaWiki and your local Event Gate to use your local schemas repository. Follow the Event Platform with local schema repositories recipe.

Install MetricsPlatform extension

MetricsPlatform extension is the way for Metrics Platform to provide experimentation capabilities. You need to install it if you want those features. Otherwise you can run without it.

You can install MetricsPlatform extension by running the following command from the root folder of your MediaWiki installation:

git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/MetricsPlatform extensions/MetricsPlatform

Configuration

Enable the extension and some features you may need by adding the following to your LocalSettings.php file:

// Enable the extension (disabled by default)
$wgMetricsPlatformEnable = true;
// Set the MPIC URL (this example considers it's running on your localhost)
$wgMetricsPlatformInstrumentConfiguratorBaseUrl = 'https://host.docker.internal';
// Enable experimentation capabilities (disabled by default)
$wgMetricsPlatformEnableExperiments = true;
// Enable experiment enrollment overriding capabilities (disabled by default)
$wgMetricsPlatformEnableExperimentOverrides = true;

Install MPIC

MPIC is a Node.js application you can use to register and manage your instruments and experiments.

Requirements and instructions to install and run MPIC are included in the README file in its repository. Once the repository is cloned and requirements are met, we recommend to follow this quick start guide section to run it locally without the login mechanism disabled.

Useful commands

  • Start the environment: docker compose up -d
  • Stop the container: docker compose stop
  • Destroy the environment: docker compose down

Using MediaWiki Vagrant

Enabling the wikimediaevents role will also include the eventlogging role for you, and set up other Event Platform backend components on MediaWiki Vagrant including EventGate.

$ vagrant roles enable wikimediaevents --provision
$ vagrant git-update

This will clone WikimediaEvents into mediawiki/extensions/WikimediaEvents and the schemas/event/secondary repository at srv/schemas/event/secondary (and also install its npm dependencies for schema materialization and tests).

Events will be written to /vagrant/logs/eventgate-events.json. eventgate logs, including validation errors, are in /vagrant/logs/eventgate-wikimedia.log.

To verify that eventgate is working properly, you can force a test event to be produced by curl-ing http://localhost:8192/v1/_test/events. You should see a test event logged into eventgate-events.json.

Using your local dev environment with eventgate-devserver

If you aren't using MediaWiki Docker or Mediawiki-Vagrant, or you'd rather have more manual control over your development environment, EventLogging comes with an 'eventgate-devserver' that will accept events and write them to a local file. Clone mediawiki/extensions/EventLogging and run

$ cd extensions/EventLogging/devserver
$ npm install --no-optional
$ npm run eventgate-devserver

This should download EventGate and other dependencies and run the eventgate-devserver accepting events at http://localhost:8192 and writing them to ./events.json. See devserver/README.md for more info.