Extension:EventLogging/Programming


 * ''See ../Data model (singular) for notes in storage in Redis

How it works
When code logs an event, it must reference a data model:

Here the data model is openTask.


 * 1) The data model is a JSON structure that is a JSON schema for the fields in the event &mdash; their names, their types, whether required or not.
 * 2) The PHP code in core or an extension has to explicitly request a particular data model.
 * 3) the MediaWiki ResourceLoader gets the data model from http://meta.wikimedia.org/wiki/Schema:openTask (and caches it)

How to make a data model

 * Meet a researcher 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.
 * Sample: m:Schema:OpenTask


 * Use the schema's talk page to link to experiments using this, discuss niceties, etc.
 * always document what code in what circumstances logs the event.

Versioning
You could: You should create a new data model when the fields you log change, so your schema name should probably include a version. (You can note changes in the experimental conditions in your own version field.)
 * create a new data model ("OpenTask2") and new code refers to that.
 * update an existing data model's page and

It's OK to have different kinds of events sharing one data model, just make fields optional. This means all the events go into one table and it's easier to query.

Built-in data fields
The JavaScript mw.eventLog.logEvent logs
 * _db
 * string, the wiki database ("enwiki", etc.)


 * _id
 * string, the modelName that is logging (in this example, "openTask")

Additions coming soon


 * _rev
 * integer, the article revision ID that the client-side code got


 * _ok
 * boolean, false if the event failed to log


 * _token
 * string, consistent user anon token

The server-side logging that picks up the events logs:
 * _timestamp
 * a server timestamp UTC.

Common data fields
Maybe some of these should be generated by the event logging code, and have an underscore prefix, so clients could just say "give me, give me


 * action
 * string; per-data model, such as 'impression', 'click', 'submit', 'accept' (a task).


 * article
 * string; wgTitle.


 * version
 * integer; a number representing changes to the condition, e.g. bump it when deploying a different version of the code

Standard data fields

 * isAnon (opposite of authenticated)
 * user has not logged-in. In JavaScript, mw.user.isAnon


 * editCount
 * how many edits a logged-in user has made. In JavaScript, request the config value wgEditCount.


 * token
 * a unique random persistent token per browser, stored in the (badly misnamed) mediaWiki.user.id cookie. In JavaScript, calling mw.user.id will generate this.

 ?? maybe have an additional session token


 * article
 * the title of the page the user is editing. In JavaScript, request the config value wgTitle.
 * note this doesn't work for Special pages and other namespaces.

Available data models
Not all of these have been converted to the new approach
 * openTask
 * in m:Schema:openTask


 * ACUX
 * includes client-side assign/impression/submit events and a server-side account_create event, both logged by Extension:E3Experiments
 * still using ClickTracking for client-side events, alas


 * edit
 * server-side event logged by EventLogging itself whenever a user creates or edits an article (on PageContentSaveComplete hook), with fields:
 * articleId, api (boolean), title, namespace, created (boolean), summary, timestamp, minor (boolean), loggedIn, userId, editCount, registered (integer timestamp)


 * mobile
 * see Event_logging/Mobile

JSON schema validation
The data model JSON format is a JSON schema, an evolving standard for specifying a data format. As of December 2012 the schemas on meta aren't validated as schemas.

Error handling
If a client attempts invalid log, EventLogging detects it's invalid and flags it, but logs it anyway.