Reading/Web/EventLogging best practices

< Reading‎ | Web

Also see Reading/Web/Quantitative Testing and WMF-wide EventLogging best practices: Extension:EventLogging/Guide


  • Schemas in MobileFrontend should be prefixed with MobileWeb
  • The talk page should be edited with the SchemaDoc template. For example Schema_talk:MobileWebSearch


EventLogging data is subject to the Wikimedia Foundation's privacy policy and Data retention guidelines. In particular, sensitive data needs to be deleted after 90 days, in a purging process that (for EventLogging) is defined by a whitelist (of non-sensitive fields) for each schema.

The Analytics Engineering team offers some thoughts on best privacy practices for when writing schemas.

See the Audiences department's Instrumentation DACI regarding the general process for creating and reviewing schemas.

Sampling rateEdit

See Reading/Web/Quantitative_Testing#Sampling_and_bucketing regarding terminology.

Be sure to check events for any newly deployed schema in its Grafana dashboard (linked on the talk page of the schema).

Consideration for experimental features in betaEdit

If wanted you may want to consider a 100% sampling rate in beta. If so, please put this in the acceptance criteria for the task which implements the schema.

Use of tokensEdit

See also Reading/Web/Quantitative_Testing#Notes on tokens

Some events need to be linkable to other events, for example Schema:Popups records several actions occurring within one pageview and within a session. This is usually done via a unique token that is generated once and used until the user closes the browser (session ID, cf. caveats), or moves to a new page (page token). See also phab:T205569. If a schema records both session tokens and page names, one of them should be purged after 90 days.


EventLogging events can be monitored in the browser console (in the Network tab, filter for request URLs containing "event" or "beacon"). But a nicer display of events as MediaWiki notifications can be activated by applying the following code in the console, while being logged in:

    .then(() => new mw.Api().saveOption('eventlogging-display-web', '1'));

(See also phab:T188640)

One may need to deactivate Do Not Track and browser extensions that might be blocking EventLogging requests (e.g. Privacy Badger).

Token miningEdit

It may be necessary to mine a token (session, pageview, or otherwise) in order to test instrumentation consistently, for example during the QA step(s).

If an A/B test is implemented using the mw.experiments.getBucket function, then the following scripts will mine a token: