Metrics Platform/How to/Setup Mediawiki for Metrics Platform

From Wikitech

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

Installation

First of all, you must download the mediawiki repository to your laptop: 

git clone https://gerrit.wikimedia.org/r/mediawiki/core.git mediawiki

Preparing the environment

  • Create a .env file, in the root folder of your mediawiki installation, with the following content:
MW_SCRIPT_PATH=/w
MW_SERVER=http://localhost:8080
MW_DOCKER_PORT=8080
MEDIAWIKI_USER=Admin
MEDIAWIKI_PASSWORD=dockerpass
XDEBUG_CONFIG=
XDEBUG_ENABLE=true
XHPROF_ENABLE=true
  • Run the following command to add your user and group to the previous file (it should add two lines to that file):
echo "MW_DOCKER_UID=$(id -u) 
MW_DOCKER_GID=$(id -g)" >> .env

Creating the environment

Execute the following three commands from the root folder of your mediawiki installation:

docker compose up -d 
docker compose exec mediawiki composer update 
docker compose exec mediawiki /bin/bash /docker/install.sh

Extensions and skins

At this moment you can go to http://localhost:8080 to see your mediawiki site already running with and old appearance and with a warning saying that the vector-2022 skin is configured but not loaded

  • Download and enable the vector skin (run the following commands from your root mediawiki folder):
cd skins/ 
git clone https://gerrit.wikimedia.org/r/mediawiki/skins/Vector
  • Add wfLoadSkin( 'Vector' ); to the LocalSettings.php file to enable this skin

(From now on we can just reload to the changes take effect)

Enabling Metrics Platform

At this moment your mediawiki site is fully installed. But we need to install and configure something else to be able to work with Metrics Platform:

  • Event Platform: This section allows you to install a more complete Event Platform environment, akin to WMF production. 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: This section shows you how 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.

Event Platform

You need to install these extensions:

To install them you can run the following command from the root folder of your mediawiki installation:

for extension in EventBus EventStreamConfig EventLogging WikimediaEvents; do
  git clone "https://gerrit.wikimedia.org/r/mediawiki/extensions/${extension}" "extensions/${extension}"
done

Again in the root folder, create a docker-compose.override.yml file with the following content:

version: "3.7"
services:
  eventlogging:
    build: "./extensions/EventLogging/devserver"
    volumes:
      - "./cache/events.json:/opt/eventlogging/events.json"
    ports:
      - "8192:8192"

Add the following to the LocalSettings.php file:

<?php

wfLoadExtensions( [
	'EventBus',
	'EventStreamConfig',
	'EventLogging',
	'WikimediaEvents'
] );

// EventBus Configuration
// ======================

// Submit all events produced on the server to the event intake service,
// including events produced by \EventLogging::submit().
$wgEventServices = [
	'*' => [ 'url' => 'http://eventlogging:8192/v1/events' ],
];
$wgEventServiceDefault = '*';
$wgEnableEventBus = 'TYPE_EVENT';

// EventStreamConfig Configuration
// ===============================

// When $wgEventLoggingStreamNames is false (not falsy), the EventLogging
// JavaScript client will treat all streams as if they are configured and
// registered.
$wgEventLoggingStreamNames = false;

// EventLogging Configuration
// ==========================

$wgEventLoggingServiceUri = 'http://localhost:8192/v1/events';

// The EventLogging JavaScript client maintains a queue of events to send to
// the event intake service (see $wgEventLoggingServiceUri above). The queue is
// flushed every $wgEventLoggingQueueLingerSeconds seconds.
//
// 1 second is just long enough for you to begin to doubt that your code is
// working...
$wgEventLoggingQueueLingerSeconds = 1;

// Disable event submission by default when running PHPUnit tests, in order to
// avoid unexpected HTTP requests caused by unexpected event creation and
// submission (e.g., in WikimediaEventsHooks) causing confusing test failures in
// unrelated extensions (see https://phabricator.wikimedia.org/T270801).
if ( defined( 'MW_PHPUNIT_TEST' ) ) {
	$wgEnableEventBus = 'TYPE_NONE';
	$wgEventLoggingServiceUri = false;
}

Finally, run the following command to create the file that will store all the produced events. The local Event Platform you have just configured will sent every event to that file (you have set that in the docker-compose.override.yaml file you have created above).

touch cache/events.json

An finally you can run the following command to launch your local Event Platform:

docker compose -f docker-compose.override.yml up -d

Working with schemas locally

You can configure MediaWiki and your local Event Gate to use your local schemas repository. Follow the Event_Platform_with_Local_Schema_Repositories recipe in the case you are working on schemas (creating or updating them) and you want to validate that everything works fine with your local instance before pushing your change.

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 the four functions that are currently available in the Metrics Platform Client Library for Javascript:

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

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 loot 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!'
} );

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');

Complete LocalSettings.php configuration

After all this, your stream configuration should be something like the following:

$wgEventStreams = [
	// To test mw.eventLog.submit()
	 'submit_stream' => [
		 'schema_title' => '/test/event/1.0.0',
		 'producers' => [
			 'metrics_platform_client' => [
				 'provide_values' => [
					 'performer_is_logged_in',
				 ]
			 ],
		 ],
	 ],
	// To test mw.eventLog.submitClick()
	'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',
				],
			],
		],
	],
	// To test mw.eventLog.submitInteraction()
	'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 );

Useful commands

  • Start the environment: docker compose up -d
  • Stop the container: docker compose stop
  • Destroy the environment: docker compose down
Retrieved from "https://wikitech.wikimedia.org/w/index.php?title=Metrics_Platform/How_to/Setup_Mediawiki_for_Metrics_Platform&oldid=2171759"