Metrics Platform/Local development setup

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.
• 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.

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 different streams in LocalSettings.php to test some of the functions that are currently available in the Metrics Platform Client Library for Javascript:

• submitClick
• submitInteraction

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

submitClick

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

$wgEventStreams = [
    // Here are the configuration for all existing streams
    'submit_click_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 run this from the developer console in your browser and see how an event is produced taking a look at the Network tab. We can produce an event for this new stream with the following code, using only its name:

mw.eventLog.submitClick('submit_click_stream');

submitInteraction

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

$wgEventStreams = [
    // Here are the configuration for all existing streams
    'submit_interaction_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 run this from the developer console in your browser and see how an event is produced taking a loot at the Network tab. 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('submit_interaction_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.

submit

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

$wgEventStreams = [
    'submit_stream' => [
        'schema_title' => '/test/event/1.0.0',
        'producers' => [
            'metrics_platform_client' => [
                'provide_values' => [
	                'performer_is_logged_in',
                ],
            ],
        ],
    ],
];
$wgEventLoggingStreamNames = array_keys( $wgEventStreams );

Once that done, you should be able to run this from the developer console in your browser and see how an event is produced taking a look at the Network tab. In this case we are going to produce an event using directly the name of the stream, the schema and some custom data:

mw.eventLog.submit( 'submit_stream', {
    '$schema': '/test/event/1.0.0',
    'test': 'Hello from JavaScript!'
} );

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.