Extension:EventLogging/Programming


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

How it works
After you have created a schema, you must register it, by using the $wgEventLoggingSchemas configuration variable (or the EventLoggingRegisterSchemas hook if it needs to be done dynamically). For an extension supporting extension registration, that would mean adding something like to  (in this example the schema is GettingStarted;   is the schema revision ID).

This automatically creates an mw.track topic you can send event data to; EventLogging will [|take care] of logging them:

If you want to log data on the server side, there is no need to register the schema (all that does is make the javascript module loader aware of it). You can log like this:

How to make a data model
Then:
 * Meet a researcher and determine what you're going to log, name the fields to log, reusing well-known field names.
 * Create a JSON structure representing this data model in the Schema: namespace on meta, tweak it until it saves without errors.
 * Sample: m:Schema:OpenTask
 * Tip: http://jsonlint.com/ has better error reporting, copy and paste your JSON into it.
 * Tip: if you have a JSON file with desired fields and values, http://www.jsonschema.net/ will guess at a schema for it (but with extra info like "id" that we don't currently use) that you can start with.
 * Use the schema's talk page (sample) to link to experiments using this, discuss details, etc.
 * Always document what code in what circumstances logs the event
 * Developers write code to log events that match the data model.
 * The data model tells analysts what information is in the logs.

Versioning
If code tries to log an event that doesn't match the data model that EventLogging retrieved, EventLogging will log the event anyway but flag it as invalid. Since you always give a schema revision, you can edit the schema as much as you want without affecting existing code.

It's OK to have different kinds of events (often called actions) sharing one data model. That way the events go into one table and it may simplify querying and multi-dimensional analysis. Only add  to the fields that are applicable to all events.

Data fields

 * ''moved to ../Guide

Available data models
See m:Category:Schemas (active).

JSON schema validation
Each data model JSON file on meta-wiki is a JSON schema. This is an evolving standard to specify the format of JSON structures, in our case the logged event.
 * the JSON schema draft.
 * When code attempts to log an event, EventLogging only pays attention to a subset of JSON schema features, including:
 * type: boolean, integer, number, string, array, object
 * required: true/false
 * enum values
 * For details, see schemaschema.json.

Good starting code

 * The WikimediaEvents extension has working code to log server-side events in PHP in.
 * The GettingStarted extension has setup code to declare and require the "openTasks" schema resource and log to it in JavaScript, but it's gotten more elaborate in 2013.

Client-side logging

 * require your schema wherever you need to log events (it will pull in the  module which contains the   object).
 * See for API documentation.

Tips

 * In JavaScript code, use  to set common values for fields to log that don't change, such as version, the user's name, etc.
 * ../Guide lists common field names already used in schemas and the JavaScript that fills them. Don't reinvent the wheel.
 * Adjust your sampling ratio such you are not sending more than 5-10 events per sec. With 3 events per sec in 3 months you are likely to have over 2 million rows in your schema table it will be hard to query data if volume is so high.

Debugging
If code attempts to log an invalid event, EventLogging detects it's invalid and flags it, but logs it anyway. Turn on ResourceLoader debug mode to see warnings in your browser's JavaScript console about invalid events. The most likely cause of an invalid events is your page doesn't load the right schema. In your browser's JavaScript console, enter mw.eventLog.schemas to see which schemas have been loaded on the current page.

Monitoring events

 * Client-side event logging works by requesting a beacon image event.gif with the log info in its query string. 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,
 * 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 . 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:
 * To monitor events after processing, you can append an  callback after a   call, for example:

Logging clicks on links
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. 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. Details on performance issues can be found here: https://bugzilla.wikimedia.org/show_bug.cgi?id=52287