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.

1. clone EventLogging into the extensions directory:
   git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/EventLogging
2. Add the below to LocalSettings.php.
3. 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 (not strictly required, it adds Wikimedia-specific instrumentations).

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
// ======================

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

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"
services:
  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

Metrics Platform

The Metrics Platform Clients are Event Platform clients. They all use the same schema, the /analytics/mediawiki/client/metrics_event schema, when submitting events. The clients are configured via stream configuration on a per-stream basis.

Configuring your MediaWiki-Docker instance as below will configure the PHP and JS Metrics Platform Clients to log all events to a single stream, the test.all stream.

Project Setup

Configuration

LocalSettings.php

<?php

$wgEventStreams = [
    'test.all' => [
        'schema_title' => '/analytics/mediawiki/client/metrics_event',
        'producers' => [
            'metrics_platform_client' => [
                'events' => [ '' ], // Matches all event names
            ],
        ],
    ],
];
$wgEventLoggingStreamNames = [ 'test.all' ];

Navigate to http://localhost:8080/wiki/Main_Page and run this in the JavaScript console of your browser's developer tools:

mw.eventLog.dispatch( 'test.hello_world', {
    hello: 'World!'
} );

You should see your event in the eventlogging log.

Repository (for server-side logging)

To enable server-side logging, you need to clone this repository into the mediawiki/libs directory:

• mediawiki/libs/metrics-platform

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

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