Wikimedia Product/Analytics Infrastructure/Standard

The instrumentation platform is a set of interfaces for processing instrumentation events. The goal of the instrumentation platform is to allow many different client platforms to access a common set of instrumentation capabilities. It abstracts away sensitive book-keeping logic and provides a simple, programmable interface that is shared by all developers. The instrumentation platform specializes the more general event platform, and the two should not be confused, as the event platform also carries other kinds of event traffic, such as events used to drive application behavior.

Each target platform receives a library that implements the common standard. To ensure portability, core algorithms are built with a small but well-chosen set of primitives that can be implemented in a transparent style, avoiding the use of language-specific abstractions. This makes it easier to verify critical behavior in a new target language. This core is then wrapped by an integration layer that implements platform-specific functions according to the specified contract.

Events from different platforms are statistically comparable. This property is called statistical coherence. To achieve coherence, the exact same algorithms for sampling, randomness, timestamp application, HTTP request handling, etc. need to be applied, while compensating for the ever-changing quirks of each target platform and programming language.

Instrumentation should not impact the user experience. Page load time, memory, CPU, storage, radio and battery usage must all be kept to a bare minimum. Not all MediaWiki deployments will enable instrumentation, or enable the same set. We must do our utmost to ensure graceful failure states or prevent misconfiguration.

Instrumentation is always churning and often wants to move fast in response to new data or new features. The instrumentation platform promotes such flexibility by allowing it to happen within a particular interface: stream configuration. Changes to stream configuration let certain well-understood instrument parameters be reflected in production code almost immediately, because instruments are dynamically configured at runtime. To protect the integrity of the production code, the stream configuration must be well understood and specified. The faster we want to move, the more confident we need to be that we can do so safely.

Description
Description of the software goes here.

Conformance
How conformance is determined. RFC 2199

Event
An event is a unit of structured data containing at least: The event will usually also contain additional data describing the event. Such data are specified by the type.
 * a time (at which the event occurred)
 * a type (specifying its intended data structure).

Instrumentation Event
An instrumentation event is an event carrying an observation about the software under instrumentation. They are strictly observational, and must follow a "prime directive": the software under instrumentation should behave identically whether or not the event is fired. This property allows instrumentation to be enabled or disabled at will, and ensures that regressions or interruptions in instrumentation do not degrade the actual software under instrumentation. This makes it safer for instrumentation to be managed independently, and allows systems which carry instrumentation events to be held to a lower service tier.

Instrument
An instrument is the unit of application code responsible for submitting the event data to the instrumentation platform library. The event data alone is not yet an event, as it does not have a time. The time, and other additional fields, will be added by the instrumentation platform library before the event is produced.

streams
.

Event
The event is formatted as a JSON string that can be validated against a corresponding JSONSchema event schema. The properties of an event must match a schema. The event will identify which schema it believes it matches. Instrumentation event schema descend from the instrumentation common schema. The fields of this common schema are filled out by the instrumentation platform library automatically, to make things more convenient for the engineer.

Properties can be added at any time before or after schema validation, but since schema validation is performed only once, properties added after validation may or may not conform to the schema. Some properties may be reserved, meaning that they are to be set exclusively by the software that controls a particular part of the event intake process. Tables of reserved properties are given below.

How event data changes during processing
The table below illustrates how a simple event that only carries a single string will look at each location in the process. A full description of the additional properties are given below.

Initialize
Binding of various things related to the integration layer, session change detection, etc.

Configure
Stream configuration loading.

Submit
Submit is the main algorithm of the library and is the only driver of runtime behavior post-initialization. Its steps are carried out in a particular order.

Three ways to submit
 * Submit buffered (input buffer)
 * Submit unbuffered (call submit directly)
 * Submit carbon copy (only done internally, always unbuffered)

Integration
The core algorithms make use of a number of platform-specific functions that are defined in the integration layer. These functions and their contracts are outlined below.