MediaWiki-Docker/Configuration recipes/EventLogging

Event Platform

Setting up and configuring your MediaWiki-Docker instance as below will leave you with a Wikimedia production Event Platform-like environment. You will be able to log events to a containerized EventGate instance (herein "EventGate") from both MediaWiki and JavaScript. 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
  • WikimediaEvents is not strictly required as it contains Wikimedia-specific instruments.

i.e.

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

Configuration

docker-compose.override.yml

version: "3.7"
services:
  eventlogging:
    build: "./extensions/EventLogging/devserver"
    ports:
      - "8192:8192"

LocalSettings.php

<?php

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

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

// Send 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 an 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;

Running

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:

• schemas/event/primary
• schemas/event/secondary

e.g.

for suffix in primary secondary; do
  git clone "https://gerrit.wikimedia.org/r/schemas/event/${suffix}" "cache/${suffix}"
done

Configuration

docker-composer.override.yml

version: "3.7"
  eventlogging:
    build: "./extensions/EventLogging/devserver"
    volumes:
      - "./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

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

Following on from the section above, 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

version: "3.7"
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 in docker, 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. The easiest way to avoid this is to not configure event logging when the unit tests are running. This can be done in LocalSettings.php like so:

# 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 (T270801)
$testMode = defined( "MW_PHPUNIT_TEST" );
if (!$testMode) {
	$wgEventServices = [
	  '*' => [ 'url' => 'http://eventlogging:8192/v1/events' ],
	];
	$wgEventServiceDefault = '*';
	$wgEnableEventBus = 'TYPE_EVENT';
}

// ...later, if you've also defined this:
$wgEventLoggingServiceUri = $testMode ? false : "http://localhost:8192/v1/events";

If you actually need to test the sending of events... good luck, please update this recipe if you work it out.