MediaWiki-Docker/Configuration recipes/EventLogging

Minimal setup

If you only need to satisfy a dependency on EventLogging for another extension, and/or only need to inspect or debug events from the client-side in a browser, then the Event Platform extensions and their configuration are not required. Instead the standard dependency-free installation documented on Extension:EventLogging will suffice.

clone EventLogging into the extensions directory:
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/EventLogging
Add the below to LocalSettings.php.
No step three!

wfLoadExtension( 'EventLogging' );
$wgEventLoggingBaseUri = '/beacon/event';
$wgEventLoggingServiceUri = '/beacon/intake-analytics';
$wgEventLoggingStreamNames = false;

Event Platform

Follow the below steps to create 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.

Project Setup

Extensions

You need to install these extensions:

EventBus
EventStreamConfig
EventLogging
WikimediaEvents (required to work on Wikimedia-specific instrumentation, including Metrics Platform instruments).

To install these extensions, 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

Configuration

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

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:

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;
}

// Same-host beacon
$wgEventLoggingBaseUri = '/beacon/event';

Running

Finally, run the following command to create the file that will store all the produced events. As configured in docker-compose.override.yaml, your local Event Platform will send every event to that file.

touch cache/events.json

Finally, run the following command to launch your local Event Platform:

docker compose up --detach
docker compose logs --no-log-prefix --follow eventlogging

You can test the above by running this in your browser's JavaScript console:

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

Event Platform with Local Schema Repositories

Iterating on the above, setting up and configuring your MediaWiki-Docker instance as below will reconfigure EventGate to validate events against schemas from clones of the schema repositories.

Project Setup

Repositories

You need to clone these repositories into the cache directory:

e.g.

for suffix in primary secondary; do
  git clone "https://gitlab.wikimedia.org/repos/data-engineering/schemas-event-${suffix}.git" "cache/${suffix}"
done

Configuration

`docker-compose.override.yml`

services:
  eventlogging:
    build: "./extensions/EventLogging/devserver"
    volumes:
      - "./cache/events.json:/opt/eventlogging/events.json"
      - "./cache/eventgate.config.yaml:/opt/eventlogging/eventgate.config.yaml"
      - "./cache/primary:/opt/eventlogging/primary"
      - "./cache/secondary:/opt/eventlogging/secondary"
    ports:
      - "8192:8192"

`cache/eventgate.config.yaml`

# See extension/EventLogging/devserver/eventlogging.config.yaml and
# https://gerrit.wikimedia.org/r/plugins/gitiles/eventgate-wikimedia/+/refs/heads/master/config.yaml
# for detail.

num_workers: 0
worker_heap_limit_mb: 200
logging:
  level: trace

services:
  - name: eventgate-devserver
    module: eventgate
    entrypoint: app
    conf:
      port: 8192
      max_body_size: 1mb
      eventgate_factory_module: "eventgate-wikimedia/eventgate-wikimedia-dev"

      schema_base_uris:
        - ./primary/jsonschema
        - ./secondary/jsonschema

      output_path: ./events.json
      should_pretty_print: false

Running

touch cache/events.json
docker compose up --force-recreate eventlogging
docker compose logs --no-log-prefix --follow eventlogging

Legacy EventLogging

In the legacy EventLogging pipeline, schemas were defined and documented on metawiki. Even though the legacy EventLogging pipeline is being migrated away from, you might still be called on to modify an instrument that uses one such schema.

Setting up and configuring your MediaWiki-Docker instance as below will allow you to log events to a containerized legacy EventLogging event intake service.

Project Setup

Configuration

`docker-compose.override.yml`

services:
  eventlogging-legacy:
    image: docker-registry.wikimedia.org/dev/eventlogging:0.0.1
    ports:
      - "8100:8100"

`LocalSettings.php`

<?php

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

// ...

$wgEventLoggingBaseUri = 'http://localhost:8100/event.gif';

Running

docker compose up --detach
docker compose logs --no-log-prefix --follow eventlogging-legacy

Unit testing

If you need to run PHPUnit tests, any test which incidentally causes event logging to occur will cause PHPUnit to error immediately with HTTP requests to http://eventlogging:8192/v1/events blocked. Use MockHttpTrait. In the example LocalSettings.php above, server-side event submission is disabled whilst the PHPUnit tests are running. If you actually need to test the sending of events... good luck, please update this recipe if you work it out.