Extension:EventLogging
| EventLogging Release status: stable |
|||
|---|---|---|---|
| Implementation | Special page, Database, ContentHandler | ||
| Description | Provides a framework for logging analytic events | ||
| Author(s) | Ori.livnehtalk | ||
| Latest version | continuous updates | ||
| Compatibility policy | release branches | ||
| MediaWiki | 1.32+ | ||
| PHP | 5.5+ | ||
| Database changes | No | ||
| License | GNU General Public License 2.0 or later | ||
| Download | |||
|
|||
| Translate the EventLogging extension if it is available at translatewiki.net | |||
| Check usage and version matrix. | |||
| Vagrant role | eventlogging | ||
| Issues | Open tasks · Report a bug | ||
The EventLogging extension facilitates the collection of metrics on how users interact with MediaWiki's interface. The Wikimedia Foundation captures this data and analyses it in aggregate to better understand how readers and editors interact with our site, to identify usability or performance problems, and to provide feedback for features engineers, with the overarching goal of driving improvements to user experience.
Contents
Features[edit]
- EventLogging supports client-side logging from JavaScript and server-side logging from PHP.
- The events are JSON objects defined by JSON schemas that can be edited on a MediaWiki server in a Schema: namespace; the latter feature is generally useful for storing other structured data in wiki pages.
- The extension includes much back-end code for transporting, parsing and loading these events into SQL tables (automatically generated from the same schemas) and MongoDB collections. The details of these components are specific to Wikimedia Foundation's configuration.
Installation[edit]
- If using Vagrant, install with
vagrant roles enable eventlogging --provision
- Manual installation
- Download and place the file(s) in a directory called
EventLoggingin yourextensions/folder.
- Add the following code at the bottom of your LocalSettings.php:
wfLoadExtension( 'EventLogging' ); $wgEventLoggingBaseUri = 'http://localhost:8080/event.gif'; $wgEventLoggingFile = '/var/log/mediawiki/events.log';
- If you would like to express a conditional dependency on EventLogging in your extension, see this sample code snippet.
Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
Configuring the schema location[edit]
By default, the extension will look for schemas on Meta-Wiki. The relevant default settings are:
$wgEventLoggingSchemaApiUri = 'https://meta.wikimedia.org/w/api.php';
$wgEventLoggingDBname = 'metawiki';
To use local schemas, or schemas from the central wiki of your own wikifarm, you need to override these. E.g. to use the Schema namespace of the local wiki, set
$wgEventLoggingSchemaApiUri = $wgServer . '/w/api.php';
$wgEventLoggingDBname = $wgDBname;
(and ensure the user account that will create the schemas is autoconfirmed).
Documentation[edit]
- /Guide to developing and deploying EventLogging schemas, and more
- /Programming has tips and suggestions for developers writing code to log events
- /Events
- /Comparison notes
- /UserAgentSanitization
- EventLogging system architecture (Wikitech), Information about the EventLogging backend on Wikimedia sites, includes further instructions for developers and data analysts
For developers[edit]
A thorough guide[edit]
If you want to log events with EventLogging, read Extension:EventLogging/Guide.
Developer setup[edit]
As a developer, you will want to set up and use EventLogging on your development wiki to simulate its use in production.
Sanity checking your setup[edit]
Your local development wiki must be running some cache server, such as memcached.
$wgMainCacheType = CACHE_MEMCACHED;
$wgMemCachedServers = array( '127.0.0.1:11211' ); // this matches Debian /etc/memcached
EventLogging.php describes the EventLogging configuration variables.
If not using MediaWiki-Vagrant, you will need to clone eventlogging server repository for local development.
So you can set
$wgEventLoggingBaseUri = 'http://localhost:8100/event.gif';
and run export PYTHONPATH=./server && server/bin/eventlogging-devserver in a terminal to see events. The MediaWiki-Vagrant server "appliance" uses port 8080, so you may want to use another port like 8081 for event.gif requests.
To verify your setup, browse to any page of your wiki, and in a JavaScript console enter
mw.loader.using( 'ext.eventLogging' ); // load the core module
mw.loader.getState( 'ext.eventLogging' ); // should be "ready"
mw.eventLog.logEvent( null, { "foo": 42 } );
The last line will generate console warnings in debug mode as null is not a known schema, but eventlogging-devserver should dump the event along with its own warnings.
For server-side events, set $wgEventLoggingFile to a local file writable by the PHP/Web server, and in a terminal run tail -f on that file.
This will dump any calls to the PHP EventLogger::LogEvent() function.
Using mediawiki-vagrant[edit]
If you develop using mediawiki-vagrant, all of the above is encapsulated in the eventlogging role. To enable it, do
vagrant roles enable eventlogging vagrant provision
This will start eventlogging-devserver listening on port 8100. Apache will be configured to proxy events from localhost:8080/event.gif to the eventlogging-devserver. You should be able to see your events in /vagrant/logs/eventlogging.log. eventlogging-devserver daemon output can be found in /var/log/upstart/eventlogging-devserver.log
For JavaScript development[edit]
If working on the javascript client, you'll need to install dependencies with npm install from the folder you're developing in. Then you can use ./node_modules/grunt/bin/grunt eslint to lint for example. The "How to run tests" section below points out how to see JavaScript test results.
Tips[edit]
Read /Guide to learn about creating and using a proper schema for your event.
Don't use a schema name like "MyFakeTest" during development. Since schemas are referenced by MediaWiki revision ID, development versions won't conflict with production, so you should always use a real name and can point to the production wiki holding schemas ($wgEventLoggingSchemaApiUri) during development.
Your code that logs events can fail if EventLogging is not available, or it can have a soft dependency.
How to run tests[edit]
There are PHP tests, python tests, and JavaScript tests.
To run Javascript tests, visit Special:JavaScriptTest/qunit on your development wiki. (see: Manual:JavaScript unit testing)
To run PHP tests, we use PHPUnit. Make sure it is installed, see: Manual:PHP unit testing/Installing PHPUnit). Then
$ vagrant ssh
> vagrant@mediawiki-vagrant:/vagrant/mediawiki/extensions/EventLogging/tests$ php /vagrant/mediawiki/tests/phpunit/phpunit.php
EventLoggingExtensionFunctionsTest.php
To run eventlogging server python tests in vagrant you need to install tox. If you use Windows, may also need to clone it to a directory that is not shared between guest and host (to work around an apparent VirtualBox shared folder issue). E.g.:
> vagrant@mediawiki-vagrant:/vagrant/mediawiki/extensions/EventLogging$ git clone . ~/EventLogging > vagrant@mediawiki-vagrant:/vagrant/mediawiki/extensions/EventLogging$ sudo pip install tox > vagrant@mediawiki-vagrant:/vagrant/mediawiki/extensions/EventLogging$ cd ~/EventLogging > vagrant@mediawiki-vagrant:/vagrant/mediawiki/extensions/EventLogging$ git submodule update --init # to get server/ checked out
Then, run tox:
> tox
Note that tox tries to run tests for Python 2.7 and Python 3.4. EventLogging runs with Python 2.7 in production. If you want to install Python3 in vagrant please run:
> sudo apt-get install python3
How to run flake8[edit]
> vagrant@mediawiki-vagrant:/vagrant/mediawiki/extensions/EventLogging$ tox -e flake8
| This extension is being used on one or more Wikimedia projects. This probably means that the extension is stable and works well enough to be used by such high-traffic websites. Look for this extension's name in Wikimedia's CommonSettings.php and InitialiseSettings.php configuration files to see where it's installed. A full list of the extensions installed on a particular wiki can be seen on the wiki's Special:Version page. |
- GPL licensed extensions
- Stable extensions
- Extensions without an image
- Special page extensions
- Database extensions
- ContentHandler extensions
- Extensions in Wikimedia version control
- CanonicalNamespaces extensions
- BeforePageDisplay extensions
- ResourceLoaderGetConfigVars extensions
- ResourceLoaderTestModules extensions
- ResourceLoaderRegisterModules extensions
- GetPreferences extensions
- CodeEditorGetPageLanguage extensions
- EditFilterMergedContent extensions
- MovePageIsValidMove extensions
- ApiMain::moduleManager extensions
- All extensions
- Extensions used on Wikimedia
- Analytics extensions
- Statistics extensions