Extension:EventLogging/Programming

See Extension:EventLogging/Guide for a comprehensive introduction to EventLogging, developing and deploying EventLogging schemas, and more.

How it worksEdit

After you have created a schema, you must add an entry to $wgEventStreams stream configuration, and also to $wgEventLoggingStreamNames. $wgEventStreams is where your event stream is declared, and it specifies which schema the events in the stream have. $wgEventLoggingStreamNames registers the stream for use with the EventLogging extension. See https://wikitech.wikimedia.org/wiki/Event_Platform/Instrumentation_How_To for more in depth instructions.

ProgrammingEdit

Good starting codeEdit

Client-side loggingEdit

  • require your schema wherever you need to log events (it will pull in the ext.eventLogging module which contains the mw.eventLog object).
  • See modules/ext.eventLogging/core.js for API documentation.

DebuggingEdit

If code attempts to log an invalid event, EventLogging logs it anyway. If you want to enable informational validation (does not affect logging) see: https://www.mediawiki.org/wiki/Extension:EventLogging/Guide#See_logging_in_your_browser. If the logged event has a revision of -1, it's possible you haven't registered your Schema correctly.

Monitoring eventsEdit

  • Client-side event logging works by sending POST HTTP request to $wgEventLoggingServiceUri with the the JSON events in the POST body. To see the log events you can
    • watch for this request in your browser's network console,
    • look for it in your web server's access logs, or
    • run the toy web server server/bin/eventlogging-devserver in the EventLogging extension which pretty-prints the query string.
  • An alternative to the above is to enable the more user-friendly debugging UI introduced in Gerrit #I1ac4a5. Currently, the debugging UI is shipped to all users but is enabled via a hidden user preference, which can only be set by pasting the following into your browser's JavaScript console:
mw.loader.using('mediawiki.api.options')
    .then(
        () => new mw.Api().saveOption('eventlogging-display-web', '1')
    );
  • To monitor events after processing, you can append an then callback after a logEvent call, for example:
mw.eventLog.logEvent('MySchema', {foo: 'bar'}).then(
    () => {
        console.log('A MySchema event has been sent!');
        
        // All validation errors will have been tracked via the
        // 'eventlogging.error' topic. Since I0bf3bd91, however, there's no
        // easy way to detect if the event that was logged was valid.
    },
    () => console.warn('Couldn\'t log the MySchema event!')
);

Logging clicks on linksEdit

Often you want to log clicks on links. If these take the user away from the current page, there's a chance that the browser will move to the new page before the request for the beacon image makes it onto the network, and the browser will drop the request. The E3 team experimented with using deferred promises to deal with this, but that introduced known and unknown unknowns. task T44815 is related to this issue.

There are significant performance concerns regarding logging before showing the next page and our recommendation is not to do that until the new beacon API becomes available [1]. Details on performance issues can be found here: https://bugzilla.wikimedia.org/show_bug.cgi?id=52287

See alsoEdit