Wikimedia Product/Analytics Infrastructure/Standard

The instrumentation platform is a set of interfaces for processing instrumentation events. 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.

Introduction
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.

Event
An event is a JSON string that can be validated against a corresponding JSONSchema event schema. The related phrase event data refers to the data structure that, when serialized as a JSON string, becomes the event.

Event data is the collection of properties (key, value pairs) that together represent an software event at a discrete moment in time. Its properties should match a schema. Most of these properties will be provided as the second argument in. Others may be provided automatically by the event platform library.

Reserved properties
Some properties are common to all schema in our system, meaning they will appear on every event regardless of how its schema is otherwise defined. To make this more convenient, the event platform client automatically manages these properties, which are enumerated below. Anything not enumerated below is unreserved. These properties originate from a combination of EventGate and the common schema which most schema inherit (LINK).

meta.id

 * MUST be UUID format (see schema)
 * SHOULD provide sufficient uniqueness (see defn of sufficient)
 * MAY be assigned a value server-side

The purpose of this field is to allow the intake to recognize events that have been duplicated as a result of bugs in the user agent. For applications where this is not necessary, it may be left unset, according to the default rules in the schema.

meta.dt

 * MUST be recorded as UTC
 * MUST be formatted as ISO 8601 (see RFC 3339)
 * MUST support millisecond resolution
 * SHOULD be assigned a value client side
 * MAY be assigned a value server side

Millisecond resolution is necessary to discriminate between events that may be sent during the same second as a result of bursting transmission. If value assigned by client, MUST be generated according to client clock (see: client clocks. MAY be assigned a value server-side. Records when the event was triggered. Date/time MUST be recorded as UTC. Format MUST be ISO 8601 (see RFC 3339) and MUST support millisecond resolution. Millisecond resolution is necessary to discriminate between events that may be sent during the same second as a result of bursting transmission. If value assigned by client, MUST be generated according to client clock (see: client clocks). MAY be assigned a value server-side.

meta.stream

 * MUST be provided a value by the client
 * SHOULD match a stream registered with stream configuration service

Name of the stream to which this event belongs. SHOULD match a stream registered with the stream configuration service. If such a stream exists, its stream configuration will be retrieved and if its  field value matches the value of the event object's   field, then validation will proceed, otherwise it will be rejected.

$schema

 * MUST be provided a value by the client
 * SHOULD match the value of  in the  stream configuration corresponding to.

Reference to the JSONSchema schema which this event object should be validated against. Its value SHOULD match the value of  in the  stream configuration corresponding to. Every event should match a schema. An event signals which schema it believes it matches, by setting its  property to the address of that schema in the public schema repository. The intake server (e.g. EventGate) will attempt to validate the event against this schema.