Analytics refactoring (#676)

* wip: initial version of the new AnalyticsAdapter.

* ref: Restructures the ICE duration and state change events.

* ref: Restructures the JitsiLocalTrack events.

* ref: Restructures the TTFM events.

* ref: Updates the user feedback event.

* ref: Restructures the _CONNECTION_TIMES_ and TTFM events.

* ref: Restructures the BRIDGE_DOWN and NO_DATA_FROM_SOURCE events.

* ref: Restructures the FOCUS_LEFT event.

* ref: Restructures the DATA_CHANNEL_OPEN event.

* ref: Removes the ICE_FAILED event (it is a duplicate of a state change event).

* ref: Restructures the device list events.

Uses one event per device, since the new format does not allow non-atomic attributes.

* fix: Does not obey "unmute" commands from the focus.

* ref: Restructures the "remotely muted" event.

* ref: Restructures the CONFERENCE_ERROR events.

* ref: Removes the CONNECTION_INTERRUPTED event

We can use ICE_STATE_CHANGED instead.

* ref: Renames isreconnect to isReconnect.

* ref: Removes the CONNECTION_RESTORED event. Use ICE state changes instead.

* ref: Restructures the p2p events.

* ref: Restructures the jingle events.

* ref: Restructures the RTP statistics event.

* ref: Restructures the CONNECTION_FAILED and DISCONNECTED events.

* ref: Restructures the getUserMedia analytics events.

* ref: Cleans up AnalyticsEvents and restructures some of the events.

* fix: Adds error logs to the analytics adapter.

* ref: Refactor Statistics.sendEventToAll

Renames to sendEventAndLog, supports the object-based API, uses the
function where appropriate.

* fix: Addresses PR feedback.

* fix: Addresses Lyubomir's feedback.

* ref: Remove unused functions, adds documentation.

* feat: Adds a Statistics.sendAnalytics shortcut.

* ref: Uses the conference name as the default containerId.

* fix: Adrdesses Lenny's feedback.

* fix: Addresses more feedback.

* fix: Uses 'operational' as the default event type.

* doc: Updates the documentation.

* fix: Fixes adding of permanent properties.

* ref: Uses consistent naming for events' attributes.

Uses "_" as a separator instead of camel case or ".".

* feat: Adds the conference name as a permanent property automatically.

* ref: Don't expose Setting.machineId.

* fix: Adds a "p2p" attribute to jingle events.

* ref: Uses "action" instead of "name".

* ref: Uses underscore in events' attribute names.

* ref: Logs a message to the logger/console

instead of callstats in sendAnalyticsAndLog().

JitsiConference.js

@@ -2,13 +2,15 @@
 import { Strophe } from 'strophe.js';
 
 import {
+    ACTION_JINGLE_RESTART,
+    ACTION_JINGLE_SI_RECEIVED,
+    ACTION_JINGLE_TERMINATE,
+    ACTION_P2P_ESTABLISHED,
+    ACTION_P2P_FAILED,
+    ACTION_P2P_SWITCH_TO_JVB,
     ICE_ESTABLISHMENT_DURATION_DIFF,
-    P2P_ESTABLISHED,
-    P2P_FAILED,
-    P2P_SWITCH_TO_JVB,
-    SESSION_INITIATE,
-    SESSION_RESTART,
-    SESSION_TERMINATE
+    createJingleEvent,
+    createP2PEvent
 } from './service/statistics/AnalyticsEvents';
 import AvgRTPStatsReporter from './modules/statistics/AvgRTPStatsReporter';
 import ComponentsVersions from './modules/version/ComponentsVersions';
@@ -1452,16 +1454,17 @@ JitsiConference.prototype._acceptJvbIncomingCall = function(
     this.jvbJingleSession = jingleSession;
     this.room.connectionTimes['session.initiate'] = now;
 
-    // Log "session.restart"
     if (this.wasStopped) {
-        Statistics.sendEventToAll(SESSION_RESTART);
+        Statistics.sendAnalyticsAndLog(
+            createJingleEvent(ACTION_JINGLE_RESTART, { p2p: false }));
     }
 
-    Statistics.analytics.sendEvent(
-        SESSION_INITIATE,
+    Statistics.sendAnalytics(createJingleEvent(
+        ACTION_JINGLE_SI_RECEIVED,
         {
-            value: now - this.room.connectionTimes['muc.joined']
-        });
+            p2p: false,
+            value: now
+        }));
     try {
         jingleSession.initialize(false /* initiator */, this.room, this.rtc);
     } catch (error) {
@@ -1586,6 +1589,8 @@ JitsiConference.prototype._rejectIncomingCall = function(
 
 /**
  * Handles the call ended event.
+ * XXX is this due to the remote side terminating the Jingle session?
+ *
  * @param {JingleSessionPC} jingleSession the jingle session which has been
  * terminated.
  * @param {String} reasonCondition the Jingle reason condition.
@@ -1602,7 +1607,8 @@ JitsiConference.prototype.onCallEnded = function(
     if (jingleSession === this.jvbJingleSession) {
         this.wasStopped = true;
 
-        Statistics.sendEventToAll(SESSION_TERMINATE);
+        Statistics.sendAnalytics(
+            createJingleEvent(ACTION_JINGLE_TERMINATE, { p2p: false }));
 
         // Stop the stats
         if (this.statistics) {
@@ -2087,9 +2093,14 @@ JitsiConference.prototype._onIceConnectionFailed = function(session) {
         // and "bad" connection
         Statistics.analytics.addPermanentProperties({ p2pFailed: true });
 
-        // Log analytics event, but only for the initiator to not count it twice
-        if (this.p2pJingleSession && this.p2pJingleSession.isInitiator) {
-            Statistics.sendEventToAll(P2P_FAILED);
+        if (this.p2pJingleSession) {
+            Statistics.sendAnalyticsAndLog(
+                createP2PEvent(
+                    ACTION_P2P_FAILED,
+                    {
+                        initiator: this.p2pJingleSession.isInitiator
+                    }));
+
         }
         this._stopP2PSession('connectivity-error', 'ICE FAILED');
     }
@@ -2238,9 +2249,9 @@ JitsiConference.prototype._onIceConnectionEstablished = function(
         const establishmentDurationDiff
             = this.p2pEstablishmentDuration - this.jvbEstablishmentDuration;
 
-        Statistics.analytics.sendEvent(
+        Statistics.sendAnalytics(
             ICE_ESTABLISHMENT_DURATION_DIFF,
-            { 'value': establishmentDurationDiff });
+            { value: establishmentDurationDiff });
     }
 
     if (done) {
@@ -2258,7 +2269,6 @@ JitsiConference.prototype._onIceConnectionEstablished = function(
         logger.info('Not removing remote JVB tracks - no session yet');
     }
 
-    // Add remote tracks
     this._addRemoteP2PTracks();
 
     // Stop media transfer over the JVB connection
@@ -2266,14 +2276,16 @@ JitsiConference.prototype._onIceConnectionEstablished = function(
         this._suspendMediaTransferForJvbConnection();
     }
 
-    // Start remote stats
     logger.info('Starting remote stats with p2p connection');
     this.statistics.startRemoteStats(this.p2pJingleSession.peerconnection);
 
-    // Log the P2P established event
-    if (this.p2pJingleSession.isInitiator) {
-        Statistics.sendEventToAll(P2P_ESTABLISHED);
-    }
+    Statistics.sendAnalyticsAndLog(
+        createP2PEvent(
+            ACTION_P2P_ESTABLISHED,
+            {
+                initiator: this.p2pJingleSession.isInitiator
+            }));
+
 };
 
 /**
@@ -2541,7 +2553,8 @@ JitsiConference.prototype._maybeStartOrStopP2P = function(userLeftEvent) {
 
         // Log that there will be a switch back to the JVB connection
         if (this.p2pJingleSession.isInitiator && peerCount > 1) {
-            Statistics.sendEventToAll(P2P_SWITCH_TO_JVB);
+            Statistics.sendAnalyticsAndLog(
+                createP2PEvent(ACTION_P2P_SWITCH_TO_JVB));
         }
         this._stopP2PSession();
     }

JitsiConferenceEventManager.js

@@ -2,14 +2,12 @@
 import { Strophe } from 'strophe.js';
 
 import {
-    _CONNECTION_TIMES_,
-    BRIDGE_DOWN,
-    CONFERENCE_ERROR_,
-    CONNECTION_INTERRUPTED,
-    CONNECTION_RESTORED,
-    DATA_CHANNEL_OPEN,
-    FOCUS_LEFT,
-    REMOTELY_MUTED
+    ACTION_JINGLE_SA_TIMEOUT,
+    createBridgeDownEvent,
+    createConnectionStageReachedEvent,
+    createFocusLeftEvent,
+    createJingleEvent,
+    createRemotelyMutedEvent
 } from './service/statistics/AnalyticsEvents';
 import AuthenticationEvents
     from './service/authentication/AuthenticationEvents';
@@ -51,14 +49,6 @@ export default function JitsiConferenceEventManager(conference) {
                 track.isMuted(),
                 track.getType());
         });
-    conference.on(
-        JitsiConferenceEvents.CONNECTION_INTERRUPTED,
-        Statistics.sendEventToAll.bind(
-            Statistics, CONNECTION_INTERRUPTED));
-    conference.on(
-        JitsiConferenceEvents.CONNECTION_RESTORED,
-        Statistics.sendEventToAll.bind(
-            Statistics, CONNECTION_RESTORED));
 }
 
 /**
@@ -85,11 +75,14 @@ JitsiConferenceEventManager.prototype.setupChatRoomListeners = function() {
     });
 
     chatRoom.addListener(XMPPEvents.AUDIO_MUTED_BY_FOCUS,
-        value => {
-            Statistics.analytics.sendEvent(REMOTELY_MUTED);
+        () => {
+            // TODO: Add a way to differentiate between commands which caused
+            // us to mute and those that did not change our state (i.e. we were
+            // already muted).
+            Statistics.sendAnalytics(createRemotelyMutedEvent());
 
             // set isMutedByFocus when setAudioMute Promise ends
-            conference.rtc.setAudioMute(value).then(
+            conference.rtc.setAudioMute(true).then(
                 () => {
                     conference.isMutedByFocus = true;
                 },
@@ -110,17 +103,24 @@ JitsiConferenceEventManager.prototype.setupChatRoomListeners = function() {
         () => {
             this.conference.isJvbConnectionInterrupted = false;
 
+            // TODO: Move all of the 'connectionTimes' logic to its own module.
             Object.keys(chatRoom.connectionTimes).forEach(key => {
-                const value = chatRoom.connectionTimes[key];
-                const eventName = `conference.${_CONNECTION_TIMES_}${key}`;
+                const event
+                    = createConnectionStageReachedEvent(
+                        `conference_${key}`,
+                        { value: chatRoom.connectionTimes[key] });
 
-                Statistics.analytics.sendEvent(eventName, { value });
+                Statistics.sendAnalytics(event);
             });
+
+            // TODO: Move all of the 'connectionTimes' logic to its own module.
             Object.keys(chatRoom.xmpp.connectionTimes).forEach(key => {
-                const value = chatRoom.xmpp.connectionTimes[key];
-                const eventName = `xmpp.${_CONNECTION_TIMES_}${key}`;
+                const event
+                    = createConnectionStageReachedEvent(
+                        `xmpp_${key}`,
+                        { value: chatRoom.xmpp.connectionTimes[key] });
 
-                Statistics.analytics.sendEvent(eventName, { value });
+                Statistics.sendAnalytics(event);
             });
         });
 
@@ -152,7 +152,7 @@ JitsiConferenceEventManager.prototype.setupChatRoomListeners = function() {
         JitsiConferenceErrors.VIDEOBRIDGE_NOT_AVAILABLE);
     chatRoom.addListener(
         XMPPEvents.BRIDGE_DOWN,
-        () => Statistics.analytics.sendEvent(BRIDGE_DOWN));
+        () => Statistics.sendAnalytics(createBridgeDownEvent()));
 
     this.chatRoomForwarder.forward(XMPPEvents.RESERVATION_ERROR,
         JitsiConferenceEvents.CONFERENCE_FAILED,
@@ -190,20 +190,18 @@ JitsiConferenceEventManager.prototype.setupChatRoomListeners = function() {
 
     chatRoom.addListener(XMPPEvents.FOCUS_LEFT,
         () => {
-            Statistics.analytics.sendEvent(FOCUS_LEFT);
+            Statistics.sendAnalytics(createFocusLeftEvent());
             conference.eventEmitter.emit(
                 JitsiConferenceEvents.CONFERENCE_FAILED,
                 JitsiConferenceErrors.FOCUS_LEFT);
         });
 
-    const eventLogHandler
-        = reason => Statistics.sendEventToAll(`${CONFERENCE_ERROR_}.${reason}`);
-
     chatRoom.addListener(XMPPEvents.SESSION_ACCEPT_TIMEOUT,
         jingleSession => {
-            eventLogHandler(
-                jingleSession.isP2P
-                    ? 'p2pSessionAcceptTimeout' : 'sessionAcceptTimeout');
+            Statistics.sendAnalyticsAndLog(
+                createJingleEvent(
+                    ACTION_JINGLE_SA_TIMEOUT,
+                    { p2p: jingleSession.isP2P }));
         });
 
     this.chatRoomForwarder.forward(XMPPEvents.RECORDER_STATE_CHANGED,
@@ -474,10 +472,13 @@ JitsiConferenceEventManager.prototype.setupRTCListeners = function() {
 
     rtc.addListener(RTCEvents.DATA_CHANNEL_OPEN, () => {
         const now = window.performance.now();
+        const key = 'data.channel.opened';
 
-        logger.log('(TIME) data channel opened ', now);
-        conference.room.connectionTimes['data.channel.opened'] = now;
-        Statistics.analytics.sendEvent(DATA_CHANNEL_OPEN, { value: now });
+        // TODO: Move all of the 'connectionTimes' logic to its own module.
+        logger.log(`(TIME) ${key}`, now);
+        conference.room.connectionTimes[key] = now;
+        Statistics.sendAnalytics(
+            createConnectionStageReachedEvent(key, { value: now }));
 
         conference.eventEmitter.emit(JitsiConferenceEvents.DATA_CHANNEL_OPENED);
     });

JitsiConferenceEvents.js

@@ -48,11 +48,13 @@ export const CONFERENCE_LEFT = 'conference.left';
 /**
  * Indicates that the connection to the conference has been interrupted for some
  * reason.
+ * XXX This is currently fired when the *ICE* connection is interrupted.
  */
 export const CONNECTION_INTERRUPTED = 'conference.connectionInterrupted';
 
 /**
  * Indicates that the connection to the conference has been restored.
+ * XXX This is currently fired when the *ICE* connection is restored.
  */
 export const CONNECTION_RESTORED = 'conference.connectionRestored';
 

JitsiConnection.js

@@ -1,6 +1,6 @@
 import {
-    CONNECTION_DISCONNECTED_,
-    CONNECTION_FAILED_
+    CONNECTION_DISCONNECTED as ANALYTICS_CONNECTION_DISCONNECTED,
+    createConnectionFailedEvent
 } from './service/statistics/AnalyticsEvents';
 import JitsiConference from './JitsiConference';
 import * as JitsiConnectionEvents from './JitsiConnectionEvents';
@@ -25,9 +25,8 @@ export default function JitsiConnection(appID, token, options) {
 
     this.addEventListener(JitsiConnectionEvents.CONNECTION_FAILED,
         (errType, msg) => {
-            Statistics.sendEventToAll(
-                `${CONNECTION_FAILED_}.${errType}`,
-                { label: msg });
+            Statistics.sendAnalyticsAndLog(
+                createConnectionFailedEvent(errType, msg));
         });
 
     this.addEventListener(JitsiConnectionEvents.CONNECTION_DISCONNECTED,
@@ -35,13 +34,19 @@ export default function JitsiConnection(appID, token, options) {
             // we can see disconnects from normal tab closing of the browser
             // and then there are no msgs, but we want to log only disconnects
             // when there is real error
+            // XXX Do we need the difference in handling between the log and
+            // analytics event here?
             if (msg) {
-                Statistics.analytics.sendEvent(
-                    `${CONNECTION_DISCONNECTED_}.${msg}`);
+                Statistics.sendAnalytics(
+                    ANALYTICS_CONNECTION_DISCONNECTED,
+                    { message: msg });
             }
             Statistics.sendLog(
-                JSON.stringify({ id: 'connection.disconnected',
-                    msg }));
+                JSON.stringify(
+                    {
+                        id: ANALYTICS_CONNECTION_DISCONNECTED,
+                        msg
+                    }));
         });
 }
 

JitsiMeetJS.js

@@ -1,12 +1,6 @@
 /* global __filename */
 
-import {
-    GET_USER_MEDIA_DEVICE_NOT_FOUND_,
-    GET_USER_MEDIA_FAIL_,
-    GET_USER_MEDIA_FAILED_,
-    GET_USER_MEDIA_SUCCESS_,
-    GET_USER_MEDIA_USER_CANCEL_
-} from './service/statistics/AnalyticsEvents';
+import { createGetUserMediaEvent } from './service/statistics/AnalyticsEvents';
 import AuthUtil from './modules/util/AuthUtil';
 import * as ConnectionQualityEvents
     from './service/connectivity/ConnectionQualityEvents';
@@ -34,7 +28,6 @@ import RTC from './modules/RTC/RTC';
 import RTCBrowserType from './modules/RTC/RTCBrowserType';
 import RTCUIHelper from './modules/RTC/RTCUIHelper';
 import ScriptUtil from './modules/util/ScriptUtil';
-import Settings from './modules/settings/Settings';
 import Statistics from './modules/statistics/statistics';
 import * as VideoSIPGWConstants from './modules/videosipgw/VideoSIPGWConstants';
 
@@ -69,28 +62,28 @@ function getLowerResolution(resolution) {
 }
 
 /**
- * Checks the available devices in options and concatenate the data to the
- * name, which will be used as analytics event name. Adds resolution for the
- * devices.
- * @param name name of event
- * @param options gum options
- * @returns {*}
+ * Extracts from an 'options' objects with a specific format
+ * (TODO what IS the format?) the attributes which are to be logged in analytics
+ * events.
+ *
+ * @param options gum options (???)
+ * @returns {*} the attributes to attach to analytics events.
  */
-function addDeviceTypeToAnalyticsEvent(name, options) {
-    let ret = name;
-
-    if (options.devices.indexOf('audio') !== -1) {
-        ret += '.audio';
-    }
-    if (options.devices.indexOf('desktop') !== -1) {
-        ret += '.desktop';
-    }
-    if (options.devices.indexOf('video') !== -1) {
-        // we have video add resolution
-        ret += `.video.${options.resolution}`;
+function getAnalyticsAttributesFromOptions(options) {
+    const attributes = {
+        'audio_requested':
+            options.devices.includes('audio'),
+        'video_requested':
+            options.devices.includes('video'),
+        'screen_sharing_requested':
+            options.devices.includes('desktop')
+    };
+
+    if (attributes.video_requested) {
+        attributes.resolution = options.resolution;
     }
 
-    return ret;
+    return attributes;
 }
 
 /**
@@ -282,10 +275,10 @@ export default {
                 window.connectionTimes['obtainPermissions.end']
                     = window.performance.now();
 
-                Statistics.analytics.sendEvent(
-                    addDeviceTypeToAnalyticsEvent(
-                        GET_USER_MEDIA_SUCCESS_, options),
-                    { value: options });
+                Statistics.sendAnalytics(
+                    createGetUserMediaEvent(
+                        'success',
+                        getAnalyticsAttributesFromOptions(options)));
 
                 if (!RTC.options.disableAudioLevels) {
                     for (let i = 0; i < tracks.length; i++) {
@@ -334,16 +327,20 @@ export default {
                             'Retry createLocalTracks with resolution',
                             newResolution);
 
-                        Statistics.analytics.sendEvent(
-                            `${GET_USER_MEDIA_FAIL_}.resolution.${
-                                oldResolution}`);
+                        Statistics.sendAnalytics(createGetUserMediaEvent(
+                            'warning',
+                            {
+                                'old_resolution': oldResolution,
+                                'new_resolution': newResolution,
+                                reason: 'unsupported resolution'
+                            }));
 
                         return this.createLocalTracks(options);
                     }
                 }
 
-                if (JitsiTrackErrors.CHROME_EXTENSION_USER_CANCELED
-                        === error.name) {
+                if (error.name
+                        === JitsiTrackErrors.CHROME_EXTENSION_USER_CANCELED) {
                     // User cancelled action is not really an error, so only
                     // log it as an event to avoid having conference classified
                     // as partially failed
@@ -353,9 +350,14 @@ export default {
                     };
 
                     Statistics.sendLog(JSON.stringify(logObject));
-                    Statistics.analytics.sendEvent(
-                        `${GET_USER_MEDIA_USER_CANCEL_}.extensionInstall`);
-                } else if (JitsiTrackErrors.NOT_FOUND === error.name) {
+
+                    Statistics.sendAnalytics(
+                        createGetUserMediaEvent(
+                            'warning',
+                            {
+                                reason: 'extension install user canceled'
+                            }));
+                } else if (error.name === JitsiTrackErrors.NOT_FOUND) {
                     // logs not found devices with just application log to cs
                     const logObject = {
                         id: 'usermedia_missing_device',
@@ -363,19 +365,24 @@ export default {
                     };
 
                     Statistics.sendLog(JSON.stringify(logObject));
-                    Statistics.analytics.sendEvent(
-                        `${GET_USER_MEDIA_DEVICE_NOT_FOUND_}.${
-                            error.gum.devices.join('.')}`);
+
+                    const attributes
+                        = getAnalyticsAttributesFromOptions(options);
+
+                    attributes.reason = 'device not found';
+                    attributes.devices = error.gum.devices.join('.');
+                    Statistics.sendAnalytics(
+                        createGetUserMediaEvent('error', attributes));
                 } else {
                     // Report gUM failed to the stats
                     Statistics.sendGetUserMediaFailed(error);
-                    const eventName
-                        = addDeviceTypeToAnalyticsEvent(
-                            GET_USER_MEDIA_FAILED_, options);
 
-                    Statistics.analytics.sendEvent(
-                        `${eventName}.${error.name}`,
-                        { value: options });
+                    const attributes
+                        = getAnalyticsAttributesFromOptions(options);
+
+                    attributes.reason = error.name;
+                    Statistics.sendAnalytics(
+                        createGetUserMediaEvent('error', attributes));
                 }
 
                 window.connectionTimes['obtainPermissions.end']
@@ -466,14 +473,6 @@ export default {
 
     /* eslint-enable max-params */
 
-    /**
-     * Returns current machine id saved from the local storage.
-     * @returns {string} the machine id
-     */
-    getMachineId() {
-        return Settings.machineId;
-    },
-
     /**
      * Represents a hub/namespace for utility functionality which may be of
      * interest to lib-jitsi-meet clients.

JitsiTrackEvents.js

@@ -33,7 +33,7 @@ export const TRACK_MUTE_CHANGED = 'track.trackMuteChanged';
 export const TRACK_VIDEOTYPE_CHANGED = 'track.videoTypeChanged';
 
 /**
- * Indicates that the track is no receiving any data without reason(the
- * stream was stopped, etc)
+ * Indicates that the track is not receiving any data even though we expect it
+ * to receive data (i.e. the stream is not stopped).
  */
 export const NO_DATA_FROM_SOURCE = 'track.no_data_from_source';

modules/RTC/JitsiLocalTrack.js

@@ -19,8 +19,8 @@ import * as MediaType from '../../service/RTC/MediaType';
 import RTCEvents from '../../service/RTC/RTCEvents';
 import VideoType from '../../service/RTC/VideoType';
 import {
-    _NO_DATA_FROM_SOURCE,
-    _TRACK_UNMUTE
+    TRACK_UNMUTED,
+    createNoDataFromSourceEvent
 } from '../../service/statistics/AnalyticsEvents';
 import Statistics from '../statistics/statistics';
 
@@ -32,7 +32,7 @@ const logger = getLogger(__filename);
  */
 export default class JitsiLocalTrack extends JitsiTrack {
     /**
-     * Constructs new JitsiLocalTrack instanse.
+     * Constructs new JitsiLocalTrack instance.
      *
      * @constructor
      * @param {Object} trackInfo
@@ -202,9 +202,13 @@ export default class JitsiLocalTrack extends JitsiTrack {
                         = setTimeout(_onNoDataFromSourceError, 3000);
                     this._setHandler('track_unmute', () => {
                         this._clearNoDataFromSourceMuteResources();
-                        Statistics.sendEventToAll(
-                            `${this.getType()}.${_TRACK_UNMUTE}`,
-                            { value: window.performance.now() - now });
+                        Statistics.sendAnalyticsAndLog(
+                            TRACK_UNMUTED,
+                            {
+                                'media_type': this.getType(),
+                                'track_type': 'local',
+                                value: window.performance.now() - now
+                            });
                     });
                 }
             });
@@ -241,10 +245,9 @@ export default class JitsiLocalTrack extends JitsiTrack {
      */
     _fireNoDataFromSourceEvent() {
         this.emit(NO_DATA_FROM_SOURCE);
-        const eventName = `${this.getType()}.${_NO_DATA_FROM_SOURCE}`;
 
-        Statistics.analytics.sendEvent(eventName);
-        const log = { name: eventName };
+        Statistics.sendAnalytics(createNoDataFromSourceEvent(this.getType()));
+        const log = { name: NO_DATA_FROM_SOURCE };
 
         if (this.isAudioTrack()) {
             log.isReceivingData = this._isReceivingData();
@@ -712,7 +715,8 @@ export default class JitsiLocalTrack extends JitsiTrack {
     }
 
     /**
-     * Detects camera issues on ended and mute events from MediaStreamTrack.
+     * Detects camera issues, i.e. returns true if we expect this track to be
+     * receiving data from its source, but it isn't receiving data.
      *
      * @returns {boolean} true if an issue is detected and false otherwise
      */

modules/RTC/JitsiRemoteTrack.js

@@ -1,4 +1,4 @@
-import { _TTFM_ } from '../../service/statistics/AnalyticsEvents';
+import { createTtfmEvent } from '../../service/statistics/AnalyticsEvents';
 import JitsiTrack from './JitsiTrack';
 import * as JitsiTrackEvents from '../../JitsiTrackEvents';
 import RTCBrowserType from './RTCBrowserType';
@@ -223,19 +223,23 @@ export default class JitsiRemoteTrack extends JitsiTrack {
         const gumDuration
             = !isNaN(gumEnd) && !isNaN(gumStart) ? gumEnd - gumStart : 0;
 
+        // Subtract the muc.joined-to-session-initiate duration because jicofo
+        // waits until there are 2 participants to start Jingle sessions.
         const ttfm = now
             - (this.conference.getConnectionTimes()['session.initiate']
-            - this.conference.getConnectionTimes()['muc.joined'])
+                - this.conference.getConnectionTimes()['muc.joined'])
             - gumDuration;
 
         this.conference.getConnectionTimes()[`${type}.ttfm`] = ttfm;
         console.log(`(TIME) TTFM ${type}:\t`, ttfm);
-        let eventName = `${type}.${_TTFM_}`;
 
-        if (this.hasBeenMuted) {
-            eventName += '.muted';
-        }
-        Statistics.analytics.sendEvent(eventName, { value: ttfm });
+        Statistics.sendAnalytics(createTtfmEvent(
+            {
+                'media_type': type,
+                muted: this.hasBeenMuted,
+                value: ttfm
+            }));
+
     }
 
     /**

modules/RTC/RTCUtils.js

@@ -9,7 +9,7 @@
           webkitRTCPeerConnection,
           webkitURL
 */
-import { DEVICE_LIST } from '../../service/statistics/AnalyticsEvents';
+import { AVAILABLE_DEVICE } from '../../service/statistics/AnalyticsEvents';
 import CameraFacingMode from '../../service/RTC/CameraFacingMode';
 import EventEmitter from 'events';
 import { getLogger } from 'jitsi-meet-logger';
@@ -547,19 +547,29 @@ function pollForAvailableMediaDevices() {
  * @returns {void}
  */
 function sendDeviceListToAnalytics(deviceList) {
-    const devicesPropsArray
-        = deviceList.map(
-            ({ deviceId, groupId, kind, label }) => {
-                // Filter the props of the device object.
-                return {
-                    deviceId,
-                    groupId,
-                    kind,
-                    label
-                };
-            });
+    const audioInputDeviceCount
+        = deviceList.filter(d => d.kind === 'audioinput').length;
+    const audioOutputDeviceCount
+        = deviceList.filter(d => d.kind === 'audiooutput').length;
+    const videoInputDeviceCount
+        = deviceList.filter(d => d.kind === 'videoinput').length;
+    const videoOutputDeviceCount
+        = deviceList.filter(d => d.kind === 'videooutput').length;
+
+    deviceList.forEach(device => {
+        const attributes = {
+            'audio_input_device_count': audioInputDeviceCount,
+            'audio_output_device_count': audioOutputDeviceCount,
+            'video_input_device_count': videoInputDeviceCount,
+            'video_output_device_count': videoOutputDeviceCount,
+            'device_id': device.deviceId,
+            'device_group_id': device.groupId,
+            'device_kind': device.kind,
+            'device_label': device.label
+        };
 
-    Statistics.analytics.sendEvent(DEVICE_LIST, { devices: devicesPropsArray });
+        Statistics.sendAnalytics(AVAILABLE_DEVICE, attributes);
+    });
 }
 
 /**

modules/statistics/AnalyticsAdapter.js

@@ -1,130 +1,327 @@
+import {
+    TYPE_OPERATIONAL,
+    TYPE_PAGE,
+    TYPE_TRACK,
+    TYPE_UI
+} from '../../service/statistics/AnalyticsEvents';
+import { getLogger } from 'jitsi-meet-logger';
 import RTCBrowserType from '../RTC/RTCBrowserType';
 import Settings from '../settings/Settings';
 
-/**
- * Interface for analytics handlers.
- */
-class AnalyticsAbstract {
-    /**
-     *
-     */
-    sendEvent() {} // eslint-disable-line no-empty-function
-}
+const MAX_CACHE_SIZE = 100;
+
+// eslist-disable-line no-undef
+const logger = getLogger(__filename);
 
 /**
- * Handler that caches all the events.
- * @extends AnalyticsAbstract
+ * This class provides an API to lib-jitsi-meet and its users for sending
+ * analytics events. It serves as a bridge to different backend implementations
+ * ("analytics handlers") and a cache for events attempted to be sent before
+ * the analytics handlers were enabled.
+ *
+ * The API is designed to be an easy replacement for the previous version of
+ * this adapter, and is meant to be extended with more convenience methods.
+ *
+ *
+ * The API calls are translated to objects with the following structure, which
+ * are then passed to the sendEvent(event) function of the underlying handlers:
+ *
+ * {
+ *    type,
+ *
+ *    action,
+ *    actionSubject,
+ *    actionSubjectId,
+ *    attributes,
+ *    categories,
+ *    containerId,
+ *    containerType,
+ *    name,
+ *    objectId,
+ *    objectType,
+ *    source,
+ *    tags
+ * }
+ *
+ * The 'type' is one of 'operational', 'page', 'track' or 'ui', and some of the
+ * other properties are considered required according to the type.
+ *
+ * For events with type 'page', the required properties are: name.
+ *
+ * For events with type 'operational' and 'ui', the required properties are:
+ * action, actionSubject, source
+ *
+ * For events with type 'page', the required properties are:
+ * action, actionSubject, source, containerType, containerId, objectType,
+ * objectId
  */
-class CacheAnalytics extends AnalyticsAbstract {
+class AnalyticsAdapter {
     /**
-     *
+     * Creates new AnalyticsAdapter instance.
      */
     constructor() {
-        super();
+        /**
+         * Whether this AnalyticsAdapter has been disposed of or not. Once this
+         * is set to true, the AnalyticsAdapter is disabled and does not accept
+         * any more events, and it can not be re-enabled.
+         * @type {boolean}
+         */
+        this.disposed = false;
+
+        /**
+         * The set of handlers to which events will be sent.
+         * @type {Set<any>}
+         */
+        this.analyticsHandlers = new Set();
+
+        /**
+         * The cache of events which are not sent yet. The cache is enabled
+         * while this field is truthy, and disabled otherwise.
+         * @type {Array}
+         */
+        this.cache = [];
+
+        /**
+         * Map of properties that will be added to every event. Note that the
+         * keys will be prefixed with "permanent.".
+         */
+        this.permanentProperties = {};
+
+        /**
+         * The name of the conference that this AnalyticsAdapter is associated
+         * with.
+         * @type {null}
+         */
+        this.conferenceName = '';
 
-        // some events may happen before init or implementation script download
-        // in this case we accumulate them in this array and send them on init
-        this.eventCache = [];
+        this.addPermanentProperties({
+            'callstats_name': Settings.callStatsUserName,
+            'user_agent': navigator.userAgent,
+            'browser_name': RTCBrowserType.getBrowserName()
+        });
     }
 
     /**
-     * Cache analytics event.
-     * @param {String} eventName the name of the event
-     * @param {Object} data can be any JSON object
+     * Dispose analytics. Clears all handlers.
      */
-    sendEvent(eventName, data = {}) {
-        this.eventCache.push({
-            eventName,
-            data
-        });
+    dispose() {
+        this.setAnalyticsHandlers([]);
+        this.disposed = true;
     }
 
     /**
-     * Clears the cached events.
-     * @returns {Array} with the cached events.
+     * Sets the handlers that are going to be used to send analytics. Sends any
+     * cached events.
+     * @param {Array} handlers the handlers
      */
-    drainCachedEvents() {
-        const eventCacheCopy = this.eventCache.slice();
+    setAnalyticsHandlers(handlers) {
+        if (this.disposed) {
+            return;
+        }
 
-        this.eventCache = [];
+        this.analyticsHandlers = new Set(handlers);
+
+        // Note that we disable the cache even if the set of handlers is empty.
+        const cache = this.cache;
 
-        return eventCacheCopy;
+        this.cache = null;
+        if (cache) {
+            cache.forEach(event => this._sendEvent(event));
+        }
     }
 
-}
+    /**
+     * Adds a set of permanent properties to this this AnalyticsAdapter.
+     * Permanent properties will be added as "attributes" to events sent to
+     * the underlying "analytics handlers", and their keys will be prefixed
+     * by "permanent_", i.e. adding a permanent property {key: "value"} will
+     * result in {"permanent_key": "value"} object to be added to the
+     * "attributes" field of events.
+     *
+     * @param {Object} properties the properties to add
+     */
+    addPermanentProperties(properties) {
+        for (const property in properties) {
+            if (properties.hasOwnProperty(property)) {
+                this.permanentProperties[`permanent_${property}`]
+                    = properties[property];
+            }
+        }
+    }
 
-const cacheAnalytics = new CacheAnalytics();
+    /**
+     * Sets the name of the conference that this AnalyticsAdapter is associated
+     * with.
+     * @param name the name to set.
+     */
+    setConferenceName(name) {
+        this.conferenceName = name;
+        this.addPermanentProperties({ 'conference_name': name });
+    }
 
-/**
- * This class will store and manage the handlers that are going to be used.
- */
-class AnalyticsAdapter {
     /**
-     * Creates new AnalyticsAdapter instance.
+     * Sends an event with a given name and given properties. The first
+     * parameter is either a string or an object. If it is a string, it is used
+     * as the event name and the second parameter is used at the attributes to
+     * attach to the event. If it is an object, it represents the whole event,
+     * including any desired attributes, and the second parameter is ignored.
+     *
+     * @param {String|Object} eventName either a string to be used as the name
+     * of the event, or an event object. If an event object is passed, the
+     * properties parameters is ignored.
+     * @param {Object} properties the properties/attributes to attach to the
+     * event, if eventName is a string.
      */
-    constructor() {
-        this.disposed = false;
-        this.analyticsHandlers = new Set();
+    sendEvent(eventName, properties = {}) {
+        let event = null;
 
-        /**
-         * Map of properties that will be added to every event
-         */
-        this.permanentProperties = {
-            callstatsname: Settings.callStatsUserName,
-            userAgent: navigator.userAgent,
-            browserName: RTCBrowserType.getBrowserName()
-        };
+        if (typeof eventName === 'string') {
+            event = {
+                type: TYPE_OPERATIONAL,
+                action: eventName,
+                actionSubject: eventName,
+                source: eventName,
+                attributes: properties
+            };
+        } else if (typeof eventName === 'object') {
+            event = eventName;
+        }
+
+        if (!this._verifyRequiredFields(event)) {
+            logger.error(
+                `Dropping a mis-formatted event: ${JSON.stringify(event)}`);
+
+            return;
+        }
 
-        this.analyticsHandlers.add(cacheAnalytics);
+        this._sendEvent(event);
     }
 
     /**
-     * Sends analytics event.
-     * @param {String} eventName the name of the event
-     * @param {Object} data can be any JSON object
+     * Checks whether an event has all of the required fields set, and tries
+     * to fill in some of the missing fields with reasonable default values.
+     * Returns true if after this operation the event has all of the required
+     * fields set, and false otherwise (if some of the required fields were not
+     * set and the attempt to fill them in with a default failed).
+     *
+     * @param event the event object.
+     * @return {boolean} true if the event (after the call to this function)
+     * contains all of the required fields, and false otherwise.
+     * @private
      */
-    sendEvent(eventName, data = {}) {
-        const modifiedData = Object.assign({}, this.permanentProperties, data);
-
-        this.analyticsHandlers.forEach(
-            analytics =>
-                analytics.sendEvent(
-                    eventName,
-                    analytics === cacheAnalytics ? data : modifiedData
-                )
-        );
+    _verifyRequiredFields(event) {
+        if (!event) {
+            return false;
+        }
+
+        if (!event.type) {
+            event.type = TYPE_OPERATIONAL;
+        }
+
+        const type = event.type;
+
+        if (type !== TYPE_OPERATIONAL && type !== TYPE_PAGE
+            && type !== TYPE_UI && type !== TYPE_TRACK) {
+            logger.error(`Unknown event type: ${type}`);
+
+            return false;
+        }
+
+        if (type === TYPE_PAGE) {
+            return Boolean(event.name);
+        }
+
+        // Try to set some reasonable default values in case some of the
+        // parameters required by the handler API are missing.
+        event.action = event.action || event.name || event.actionSubject;
+        event.actionSubject = event.actionSubject || event.name || event.action;
+        event.source = event.source || event.name || event.action
+            || event.actionSubject;
+
+        if (!event.action || !event.actionSubject || !event.source) {
+            logger.error(
+                'Required field missing (action, actionSubject or source)');
+
+            return false;
+        }
+
+        // Track events have additional required fields.
+        if (type === TYPE_TRACK) {
+            event.objectType = event.objectType || 'generic-object-type';
+            event.containerType = event.containerType || 'conference';
+            if (event.containerType === 'conference' && !event.containerId) {
+                event.containerId = this.conferenceName;
+            }
+
+
+            if (!event.objectType || !event.objectId
+                || !event.containerType || !event.containerId) {
+                logger.error(
+                    'Required field missing (containerId, containerType, '
+                        + 'objectId or objectType)');
+
+                return false;
+            }
+        }
+
+        return true;
     }
 
     /**
-     * Dispose analytics. Clears all handlers.
+     * Saves an event to the cache, if the cache is enabled.
+     * @param event the event to save.
+     * @returns {boolean} true if the event was saved, and false otherwise (i.e.
+     * if the cache was disabled).
+     * @private
      */
-    dispose() {
-        cacheAnalytics.drainCachedEvents();
-        this.analyticsHandlers.clear();
-        this.disposed = true;
+    _maybeCacheEvent(event) {
+        if (this.cache) {
+            this.cache.push(event);
+
+            // We limit the size of the cache, in case the user fails to ever
+            // set the analytics handlers.
+            if (this.cache.length > MAX_CACHE_SIZE) {
+                this.cache.splice(0, 1);
+            }
+
+            return true;
+        }
+
+        return false;
+
     }
 
     /**
-     * Sets the handlers that are going to be used to send analytics and send
-     * the cached events.
-     * @param {Array} handlers the handlers
+     *
+     * @param event
+     * @private
      */
-    setAnalyticsHandlers(handlers) {
-        if (this.disposed) {
-            return;
+    _sendEvent(event) {
+        if (this._maybeCacheEvent(event)) {
+            // The event was consumed by the cache.
+        } else {
+            // We append the permanent properties at the time we send the event,
+            // not at the time we receive it.
+            this._appendPermanentProperties(event);
+
+            this.analyticsHandlers.forEach(handler => handler.sendEvent(event));
         }
-        this.analyticsHandlers = new Set(handlers);
-        cacheAnalytics.drainCachedEvents().forEach(
-            ev => this.sendEvent(ev.eventName, ev.data));
     }
 
     /**
-     * Adds map of properties that will be added to every event.
-     * @param {Object} properties the map of properties
+     * Extends an event object with the configured permanent properties.
+     * @param event the event to extend with permanent properties.
+     * @private
      */
-    addPermanentProperties(properties) {
-        Object.assign(this.permanentProperties, properties);
+    _appendPermanentProperties(event) {
+        if (!event.attributes) {
+            event.attributes = {};
+        }
+
+        event.attributes
+            = Object.assign(event.attributes, this.permanentProperties);
     }
+
 }
 
 export default new AnalyticsAdapter();

modules/statistics/AvgRTPStatsReporter.js

@@ -1,6 +1,6 @@
 /* global __filename */
 
-import { AVG_RTP_STATS } from '../../service/statistics/AnalyticsEvents';
+import { createRtpStatsEvent } from '../../service/statistics/AnalyticsEvents';
 import { getLogger } from 'jitsi-meet-logger';
 import * as ConnectionQualityEvents
     from '../../service/connectivity/ConnectionQualityEvents';
@@ -61,10 +61,8 @@ class AverageStatReport {
      * @param {Object} report the analytics "data" object
      */
     appendReport(report) {
-        report[this.name] = {
-            value: this.calculate(),
-            samples: this.samples
-        };
+        report[`${this.name}_avg`] = this.calculate();
+        report[`${this.name}_samples`] = JSON.stringify(this.samples);
     }
 
     /**
@@ -117,7 +115,7 @@ class ConnectionAvgStats {
          * Average round trip time reported by the ICE candidate pair.
          * @type {AverageStatReport}
          */
-        this._avgRTT = new AverageStatReport('stat_avg_rtt');
+        this._avgRTT = new AverageStatReport('rtt');
 
         /**
          * Map stores average RTT to the JVB reported by remote participants.
@@ -197,16 +195,16 @@ class ConnectionAvgStats {
 
                 const batchReport = {
                     p2p: this.isP2P,
-                    size: conference.getParticipantCount()
+                    'conference_size': conference.getParticipantCount()
                 };
 
                 if (data.transport && data.transport.length) {
                     Object.assign(batchReport, {
-                        localCandidateType:
+                        'local_candidate_type':
                             data.transport[0].localCandidateType,
-                        remoteCandidateType:
+                        'remote_candidate_type':
                             data.transport[0].remoteCandidateType,
-                        transportType: data.transport[0].type
+                        'transport_type': data.transport[0].type
                     });
                 }
 
@@ -218,13 +216,9 @@ class ConnectionAvgStats {
                         ._avgRtpStatsReporter.jvbStatsMonitor._avgEnd2EndRTT;
 
                     if (!isNaN(jvbEnd2EndRTT)) {
-                        const avgRTTDiff
-                            = this._avgRTT.calculate() - jvbEnd2EndRTT;
-
                         // eslint-disable-next-line dot-notation
-                        batchReport['stat_avg_rtt_diff'] = {
-                            value: avgRTTDiff
-                        };
+                        batchReport['rtt_diff']
+                            = this._avgRTT.calculate() - jvbEnd2EndRTT;
                     }
                 } else {
                     // Report end to end RTT only for JVB.
@@ -235,13 +229,11 @@ class ConnectionAvgStats {
 
                     if (!isNaN(avgLocalRTT) && !isNaN(avgRemoteRTT)) {
                         // eslint-disable-next-line dot-notation
-                        batchReport['stat_avg_end2endrtt'] = {
-                            value: this._avgEnd2EndRTT
-                        };
+                        batchReport['end2end_rtt_avg'] = this._avgEnd2EndRTT;
                     }
                 }
 
-                Statistics.analytics.sendEvent(AVG_RTP_STATS, batchReport);
+                Statistics.sendAnalytics(createRtpStatsEvent(batchReport));
             }
 
             this._resetAvgStats();
@@ -377,82 +369,91 @@ export default class AvgRTPStatsReporter {
 
         /**
          * Average audio upload bitrate
+         * XXX What are the units?
          * @type {AverageStatReport}
          * @private
          */
         this._avgAudioBitrateUp
-            = new AverageStatReport('stat_avg_bitrate_audio_upload');
+            = new AverageStatReport('bitrate_audio_upload');
 
         /**
          * Average audio download bitrate
+         * XXX What are the units?
          * @type {AverageStatReport}
          * @private
          */
         this._avgAudioBitrateDown
-            = new AverageStatReport('stat_avg_bitrate_audio_download');
+            = new AverageStatReport('bitrate_audio_download');
 
         /**
          * Average video upload bitrate
+         * XXX What are the units?
          * @type {AverageStatReport}
          * @private
          */
         this._avgVideoBitrateUp
-            = new AverageStatReport('stat_avg_bitrate_video_upload');
+            = new AverageStatReport('bitrate_video_upload');
 
         /**
          * Average video download bitrate
+         * XXX What are the units?
          * @type {AverageStatReport}
          * @private
          */
         this._avgVideoBitrateDown
-            = new AverageStatReport('stat_avg_bitrate_video_download');
+            = new AverageStatReport('bitrate_video_download');
 
         /**
          * Average upload bandwidth
+         * XXX What are the units?
          * @type {AverageStatReport}
          * @private
          */
         this._avgBandwidthUp
-            = new AverageStatReport('stat_avg_bandwidth_upload');
+            = new AverageStatReport('bandwidth_upload');
 
         /**
          * Average download bandwidth
+         * XXX What are the units?
          * @type {AverageStatReport}
          * @private
          */
         this._avgBandwidthDown
-            = new AverageStatReport('stat_avg_bandwidth_download');
+            = new AverageStatReport('bandwidth_download');
 
         /**
          * Average total packet loss
+         * XXX What are the units?
          * @type {AverageStatReport}
          * @private
          */
         this._avgPacketLossTotal
-            = new AverageStatReport('stat_avg_packetloss_total');
+            = new AverageStatReport('packet_loss_total');
 
         /**
          * Average upload packet loss
+         * XXX What are the units?
          * @type {AverageStatReport}
          * @private
          */
         this._avgPacketLossUp
-            = new AverageStatReport('stat_avg_packetloss_upload');
+            = new AverageStatReport('packet_loss_upload');
 
         /**
          * Average download packet loss
+         * XXX What are the units?
          * @type {AverageStatReport}
          * @private
          */
         this._avgPacketLossDown
-            = new AverageStatReport('stat_avg_packetloss_download');
+            = new AverageStatReport('packet_loss_download');
 
         /**
          * Average FPS for remote videos
          * @type {AverageStatReport}
          * @private
          */
-        this._avgRemoteFPS = new AverageStatReport('stat_avg_framerate_remote');
+        this._avgRemoteFPS = new AverageStatReport('framerate_remote');
 
         /**
          * Average FPS for remote screen streaming videos (reported only if not
@@ -461,14 +462,14 @@ export default class AvgRTPStatsReporter {
          * @private
          */
         this._avgRemoteScreenFPS
-            = new AverageStatReport('stat_avg_framerate_screen_remote');
+            = new AverageStatReport('framerate_screen_remote');
 
         /**
          * Average FPS for local video (camera)
          * @type {AverageStatReport}
          * @private
          */
-        this._avgLocalFPS = new AverageStatReport('stat_avg_framerate_local');
+        this._avgLocalFPS = new AverageStatReport('framerate_local');
 
         /**
          * Average FPS for local screen streaming video (reported only if not
@@ -477,7 +478,7 @@ export default class AvgRTPStatsReporter {
          * @private
          */
         this._avgLocalScreenFPS
-            = new AverageStatReport('stat_avg_framerate_screen_local');
+            = new AverageStatReport('framerate_screen_local');
 
         /**
          * Average pixels for remote screen streaming videos (reported only if
@@ -486,7 +487,7 @@ export default class AvgRTPStatsReporter {
          * @private
          */
         this._avgRemoteCameraPixels
-            = new AverageStatReport('stat_avg_pixels_remote');
+            = new AverageStatReport('pixels_remote');
 
         /**
          * Average pixels for remote screen streaming videos (reported only if
@@ -495,7 +496,7 @@ export default class AvgRTPStatsReporter {
          * @private
          */
         this._avgRemoteScreenPixels
-            = new AverageStatReport('stat_avg_pixels_screen_remote');
+            = new AverageStatReport('pixels_screen_remote');
 
         /**
          * Average pixels for local video (camera)
@@ -503,7 +504,7 @@ export default class AvgRTPStatsReporter {
          * @private
          */
         this._avgLocalCameraPixels
-            = new AverageStatReport('stat_avg_pixels_local');
+            = new AverageStatReport('pixels_local');
 
         /**
          * Average pixels for local screen streaming video (reported only if not
@@ -512,7 +513,7 @@ export default class AvgRTPStatsReporter {
          * @private
          */
         this._avgLocalScreenPixels
-            = new AverageStatReport('stat_avg_pixels_screen_local');
+            = new AverageStatReport('pixels_screen_local');
 
         /**
          * Average connection quality as defined by
@@ -520,7 +521,7 @@ export default class AvgRTPStatsReporter {
          * @type {AverageStatReport}
          * @private
          */
-        this._avgCQ = new AverageStatReport('stat_avg_cq');
+        this._avgCQ = new AverageStatReport('connection_quality');
 
         this._onLocalStatsUpdated = data => this._calculateAvgStats(data);
         conference.on(
@@ -674,14 +675,16 @@ export default class AvgRTPStatsReporter {
 
             const batchReport = {
                 p2p: isP2P,
-                size: confSize
+                'conference_size': confSize
             };
 
             if (data.transport && data.transport.length) {
                 Object.assign(batchReport, {
-                    localCandidateType: data.transport[0].localCandidateType,
-                    remoteCandidateType: data.transport[0].remoteCandidateType,
-                    transportType: data.transport[0].type
+                    'local_candidate_type':
+                        data.transport[0].localCandidateType,
+                    'remote_candidate_type':
+                        data.transport[0].remoteCandidateType,
+                    'transport_type': data.transport[0].type
                 });
             }
 
@@ -719,7 +722,7 @@ export default class AvgRTPStatsReporter {
 
             this._avgCQ.appendReport(batchReport);
 
-            Statistics.analytics.sendEvent(AVG_RTP_STATS, batchReport);
+            Statistics.sendAnalytics(createRtpStatsEvent(batchReport));
 
             this._resetAvgStats();
         }

modules/statistics/CallStats.js

@@ -465,17 +465,17 @@ export default class CallStats {
      *
      * @param {string} conferenceID the conference ID for which the feedback
      * will be reported.
-     * @param overallFeedback an integer between 1 and 5 indicating the
+     * @param overall an integer between 1 and 5 indicating the
      * user feedback
-     * @param detailedFeedback detailed feedback from the user. Not yet used
+     * @param comment detailed feedback from the user.
      */
-    static sendFeedback(conferenceID, overallFeedback, detailedFeedback) {
+    static sendFeedback(conferenceID, overall, comment) {
         if (CallStats.backend) {
             CallStats.backend.sendUserFeedback(
                 conferenceID, {
                     userID: CallStats.userID,
-                    overall: overallFeedback,
-                    comment: detailedFeedback
+                    overall,
+                    comment
                 });
         } else {
             logger.error('Failed to submit feedback to CallStats - no backend');

modules/statistics/statistics.js

@@ -1,9 +1,6 @@
 import EventEmitter from 'events';
 
-import {
-    FEEDBACK,
-    ICE_FAILED
-} from '../../service/statistics/AnalyticsEvents';
+import { FEEDBACK } from '../../service/statistics/AnalyticsEvents';
 import analytics from './AnalyticsAdapter';
 import CallStats from './CallStats';
 import LocalStats from './LocalStatsCollector';
@@ -470,7 +467,6 @@ Statistics.prototype.sendIceConnectionFailedEvent = function(tpc) {
     if (instance) {
         instance.sendIceConnectionFailedEvent();
     }
-    Statistics.analytics.sendEvent(ICE_FAILED);
 };
 
 /**
@@ -682,16 +678,16 @@ Statistics.sendLog = function(m) {
 /**
  * Sends the given feedback through CallStats.
  *
- * @param overall an integer between 1 and 5 indicating the user feedback
- * @param detailed detailed feedback from the user. Not yet used
+ * @param overall an integer between 1 and 5 indicating the user's rating.
+ * @param comment the comment from the user.
  */
-Statistics.prototype.sendFeedback = function(overall, detailed) {
-    CallStats.sendFeedback(this._getCallStatsConfID(), overall, detailed);
+Statistics.prototype.sendFeedback = function(overall, comment) {
+    CallStats.sendFeedback(this._getCallStatsConfID(), overall, comment);
     Statistics.analytics.sendEvent(
         FEEDBACK,
         {
-            value: overall,
-            detailed
+            rating: overall,
+            comment
         });
 };
 
@@ -711,16 +707,46 @@ Statistics.reportGlobalError = function(error) {
 };
 
 /**
- * Sends event to analytics and callstats.
- * @param {string} eventName the event name.
- * @param {Object} data the data to be sent.
+ * Sends event to analytics and logs a message to the logger/console. Console
+ * messages might also be logged to callstats automatically.
+ *
+ * @param {string | Object} event the event name, or an object which
+ * represents the entire event.
+ * @param {Object} properties properties to attach to the event (if an event
+ * name as opposed to an event object is provided).
  */
-Statistics.sendEventToAll = function(eventName, data) {
-    this.analytics.sendEvent(eventName, data);
-    Statistics.sendLog(
-        JSON.stringify(
-            {
-                name: eventName,
-                data
-            }));
+Statistics.sendAnalyticsAndLog = function(event, properties = {}) {
+    if (!event) {
+        logger.warn('No event or event name given.');
+
+        return;
+    }
+
+    let eventToLog;
+
+    // Also support an API with a single object as an event.
+    if (typeof event === 'object') {
+        eventToLog = event;
+    } else {
+        eventToLog = {
+            name: event,
+            properties
+        };
+    }
+
+    logger.log(JSON.stringify(eventToLog));
+
+    // We do this last, because it may modify the object which is passed.
+    this.analytics.sendEvent(event, properties);
+};
+
+/**
+ * Sends event to analytics.
+ *
+ * @param {string | Object} eventName the event name, or an object which
+ * represents the entire event.
+ * @param {Object} properties properties to attach to the event
+ */
+Statistics.sendAnalytics = function(eventName, properties = {}) {
+    this.analytics.sendEvent(eventName, properties);
 };

modules/xmpp/ChatRoom.js

@@ -1325,7 +1325,7 @@ export default class ChatRoom extends Listenable {
     }
 
     /**
-     *
+     * TODO: Document
      * @param iq
      */
     onMute(iq) {
@@ -1334,19 +1334,19 @@ export default class ChatRoom extends Listenable {
         if (from !== this.focusMucJid) {
             logger.warn('Ignored mute from non focus peer');
 
-            return false;
+            return;
         }
         const mute = $(iq).find('mute');
 
-        if (mute.length) {
-            const doMuteAudio = mute.text() === 'true';
-
-            this.eventEmitter.emit(
-                XMPPEvents.AUDIO_MUTED_BY_FOCUS,
-                doMuteAudio);
+        if (mute.length && mute.text() === 'true') {
+            this.eventEmitter.emit(XMPPEvents.AUDIO_MUTED_BY_FOCUS);
+        } else {
+            // XXX Why do we support anything but muting? Why do we encode the
+            // value in the text of the element? Why do we use a separate XML
+            // namespace?
+            logger.warn('Ignoring a mute request which does not explicitly '
+                + 'specify a positive mute command.');
         }
-
-        return true;
     }
 
     /**

modules/xmpp/JingleSessionPC.js

@@ -1,10 +1,8 @@
 /* global __filename, $ */
 
 import {
-    _ICE_CHECKING_DURATION,
-    _ICE_CONNECTION_STATE_,
-    _ICE_ESTABLISHMENT_DURATION,
-    _ICE_GATHERING_DURATION
+    ICE_DURATION,
+    ICE_STATE_CHANGED
 } from '../../service/statistics/AnalyticsEvents';
 import async from 'async';
 import { getLogger } from 'jitsi-meet-logger';
@@ -243,7 +241,7 @@ export default class JingleSessionPC extends JingleSession {
         this.lasticecandidate = false;
 
         // True if reconnect is in progress
-        this.isreconnect = false;
+        this.isReconnect = false;
 
         // Set to true if the connection was ever stable
         this.wasstable = false;
@@ -318,13 +316,14 @@ export default class JingleSessionPC extends JingleSession {
                 }
             } else if (!this._gatheringReported) {
                 // End of gathering
-                let eventName = this.isP2P ? 'p2p.ice.' : 'ice.';
-
-                eventName += this.isInitiator ? 'initiator.' : 'responder.';
-                eventName += _ICE_GATHERING_DURATION;
-                Statistics.analytics.sendEvent(
-                    eventName,
-                    { value: now - this._gatheringStartedTimestamp });
+                Statistics.sendAnalytics(
+                    ICE_DURATION,
+                    {
+                        phase: 'gathering',
+                        value: now - this._gatheringStartedTimestamp,
+                        p2p: this.isP2P,
+                        initiator: this.isInitiator
+                    });
                 this._gatheringReported = true;
             }
             this.sendIceCandidate(candidate);
@@ -373,12 +372,17 @@ export default class JingleSessionPC extends JingleSession {
                 `(TIME) ICE ${this.peerconnection.iceConnectionState}`
                     + ` P2P? ${this.isP2P}:\t`,
                 now);
-            const iceConnectionEventName
-                = `${this.isP2P ? 'p2p.' : ''}${_ICE_CONNECTION_STATE_}.${
-                    this.peerconnection.iceConnectionState}`;
 
-            Statistics.analytics.sendEvent(
-                iceConnectionEventName, { value: now });
+            Statistics.sendAnalytics(
+                ICE_STATE_CHANGED,
+                {
+                    p2p: this.isP2P,
+                    state: this.peerconnection.iceConnectionState,
+                    'signaling_state': this.peerconnection.signalingState,
+                    reconnect: this.isReconnect,
+                    value: now
+                });
+
             this.room.eventEmitter.emit(
                 XMPPEvents.ICE_CONNECTION_STATE_CHANGED,
                 this,
@@ -391,20 +395,21 @@ export default class JingleSessionPC extends JingleSession {
                 // Informs interested parties that the connection has been
                 // restored.
                 if (this.peerconnection.signalingState === 'stable') {
-                    if (this.isreconnect) {
+                    if (this.isReconnect) {
                         this.room.eventEmitter.emit(
                             XMPPEvents.CONNECTION_RESTORED, this);
                     }
                 }
 
                 if (!this.wasConnected && this.wasstable) {
-                    let eventName = this.isP2P ? 'p2p.ice.' : 'ice.';
 
-                    eventName += this.isInitiator ? 'initiator.' : 'responder.';
-                    Statistics.analytics.sendEvent(
-                        `${eventName}${_ICE_CHECKING_DURATION}`,
+                    Statistics.sendAnalytics(
+                        ICE_DURATION,
                         {
-                            value: now - this._iceCheckingStartedTimestamp
+                            phase: 'checking',
+                            value: now - this._iceCheckingStartedTimestamp,
+                            p2p: this.isP2P,
+                            initiator: this.isInitiator
                         });
 
                     // Switch between ICE gathering and ICE checking whichever
@@ -417,22 +422,26 @@ export default class JingleSessionPC extends JingleSession {
 
                     this.establishmentDuration = now - iceStarted;
 
-                    Statistics.analytics.sendEvent(
-                        `${eventName}${_ICE_ESTABLISHMENT_DURATION}`,
+                    Statistics.sendAnalytics(
+                        ICE_DURATION,
                         {
-                            value: this.establishmentDuration
+                            phase: 'establishment',
+                            value: this.establishmentDuration,
+                            p2p: this.isP2P,
+                            initiator: this.isInitiator
                         });
+
                     this.wasConnected = true;
                     this.room.eventEmitter.emit(
                         XMPPEvents.CONNECTION_ESTABLISHED, this);
                 }
-                this.isreconnect = false;
+                this.isReconnect = false;
                 break;
             case 'disconnected':
                 if (this.closed) {
                     break;
                 }
-                this.isreconnect = true;
+                this.isReconnect = true;
 
                 // Informs interested parties that the connection has been
                 // interrupted.

modules/xmpp/strophe.emuc.js

@@ -158,13 +158,15 @@ class MucConnectionPlugin extends ConnectionPluginListenable {
     }
 
     /**
-     *
+     * TODO: Document
      * @param iq
      */
     onMute(iq) {
         const from = iq.getAttribute('from');
         const room = this.rooms[Strophe.getBareJidFromJid(from)];
 
+        // XXX What are the semantics of the return value? Why is it sometimes
+        // undefined and sometimes a boolean?
         if (!room) {
             return;
         }

modules/xmpp/strophe.jingle.js

@@ -1,9 +1,9 @@
 /* global $, __filename */
 
 import {
-    SESSION_INITIATE_RECEIVED,
-    TRANSPORT_REPLACE_START,
-    TRANSPORT_REPLACE_SUCCESS
+    ACTION_JINGLE_TR_RECEIVED,
+    ACTION_JINGLE_TR_SUCCESS,
+    createJingleEvent
 } from '../../service/statistics/AnalyticsEvents';
 import { getLogger } from 'jitsi-meet-logger';
 import { $iq, Strophe } from 'strophe.js';
@@ -128,6 +128,11 @@ class JingleConnectionPlugin extends ConnectionPlugin {
         }
         const now = window.performance.now();
 
+        // FIXME that should work most of the time, but we'd have to
+        // think how secure it is to assume that user with "focus"
+        // nickname is Jicofo.
+        const isP2P = Strophe.getResourceFromJid(fromJid) !== 'focus';
+
         // see http://xmpp.org/extensions/xep-0166.html#concepts-session
 
         switch (action) {
@@ -145,11 +150,6 @@ class JingleConnectionPlugin extends ConnectionPlugin {
                     videoMuted === 'true');
             }
 
-            // FIXME that should work most of the time, but we'd have to
-            // think how secure it is to assume that user with "focus"
-            // nickname is Jicofo.
-            const isP2P = Strophe.getResourceFromJid(fromJid) !== 'focus';
-
             logger.info(
                 `Marking session from ${fromJid
                 } as ${isP2P ? '' : '*not*'} P2P`);
@@ -169,8 +169,6 @@ class JingleConnectionPlugin extends ConnectionPlugin {
 
             this.eventEmitter.emit(XMPPEvents.CALL_INCOMING,
                 sess, $(iq).find('>jingle'), now);
-            Statistics.analytics.sendEvent(
-                SESSION_INITIATE_RECEIVED, { value: now });
             break;
         }
         case 'session-accept': {
@@ -204,17 +202,23 @@ class JingleConnectionPlugin extends ConnectionPlugin {
         }
         case 'transport-replace':
             logger.info('(TIME) Start transport replace', now);
-            Statistics.analytics.sendEvent(
-                TRANSPORT_REPLACE_START,
-                { value: now });
+            Statistics.sendAnalytics(createJingleEvent(
+                ACTION_JINGLE_TR_RECEIVED,
+                {
+                    p2p: isP2P,
+                    value: now
+                }));
 
             sess.replaceTransport($(iq).find('>jingle'), () => {
                 const successTime = window.performance.now();
 
                 logger.info('(TIME) Transport replace success!', successTime);
-                Statistics.analytics.sendEvent(
-                    TRANSPORT_REPLACE_SUCCESS,
-                    { value: successTime });
+                Statistics.sendAnalytics(createJingleEvent(
+                    ACTION_JINGLE_TR_SUCCESS,
+                    {
+                        p2p: isP2P,
+                        value: successTime
+                    }));
             }, error => {
                 GlobalOnErrorHandler.callErrorHandler(error);
                 logger.error('Transport replace failed', error);

service/statistics/AnalyticsEvents.js

@@ -1,447 +1,415 @@
 /**
- * Note that an event's own properties and its permanent properties are
- * are merged in one object. Because of this an event should never use
- * properties with names that are already used by permanent properties
- * (unless the intention is to override a permanent property). Here is a
- * (non-exhaustive) list of currently know permanent properties:
+ * This class exports constants and factory methods related to the analytics
+ * API provided by AnalyticsAdapter. In order for entries in a database to be
+ * somewhat easily traceable back to the code which produced them, events sent
+ * through analytics should be defined here.
  *
- * abtestSuspendVideo
- * browserName
- * callstatsname
- * crossRegion
- * forceJvb121
- * region
- * roomName
- * shard
- * size
- * userAgent
- * userRegion
+ * Since the AnalyticsAdapter API can be used in different ways, for some events
+ * it is more convenient to just define the event name as a constant. For other
+ * events a factory function is easier.
  *
- * The naming convention for the constants below uses "_" as a prefix or
- * suffix to indicate that known usage of the constant prepends or appends
- * a string to the name of the event.
- */
-
-/**
- * Properties: value
+ * A general approach for adding a new event:
+ * 1. Determine the event type: track, UI, page, or operational. If in doubt use
+ * operational.
+ * 2. Determine whether the event is related to other existing events, and
+ * which fields are desired to be set: name, action, actionSubject, source.
+ * 3. If the name is sufficient (the other fields are not important), use a
+ * constant. Otherwise use a factory function.
  *
- * TODO: document, reformat
+ * Note that the AnalyticsAdapter uses the events passed to its functions for
+ * its own purposes, and might modify them. Because of this factory functions
+ * should create new objects.
  *
- * Full event names (uncertain):
- * conference.muc.joined (???)
- * conference.sharingDesktop.start (???)
- * conference.sharingDesktop.stop (???)
- * xmpp.attached (???)
- * xmpp.attaching (???)
- * xmpp.connected (???)
- * xmpp.connecting (???)
- * xmpp.session-initiate (???)
  */
-export const _CONNECTION_TIMES_ = '';
 
 /**
- * TODO: document, reformat (group together with other ICE events)
- *
- * Known full event names:
- * ice.initiator.checksDuration
- * ice.responder.checksDuration
- * p2p.ice.initiator.checksDuration
- * p2p.ice.responder.checksDuration
- *
- * Properties: value
+ * The constant which identifies an event of type "operational".
+ * @type {string}
  */
-export const _ICE_CHECKING_DURATION = 'checksDuration';
+export const TYPE_OPERATIONAL = 'operational';
 
 /**
- * TODO: document, reformat
- *
- * Known full event names:
- * ice.checking
- * ice.closed
- * ice.completed
- * ice.connected
- * ice.disconnected
- * ice.failed
- * p2p.ice.checking
- * p2p.ice.closed
- * p2p.ice.completed
- * p2p.ice.connected
- * p2p.ice.disconnected
- * p2p.ice.failed
- *
- * Properties: value
+ * The constant which identifies an event of type "page".
+ * @type {string}
  */
-export const _ICE_CONNECTION_STATE_ = 'ice';
+export const TYPE_PAGE = 'page';
 
 /**
- * TODO: document, reformat (group together with other ICE events)
- *
- * Known full event names:
- * ice.initiator.establishmentDuration
- * ice.responder.establishmentDuration
- * p2p.ice.initiator.establishmentDuration
- * p2p.ice.responder.establishmentDuration
- *
- * Properties: value
+ * The constant which identifies an event of type "track".
+ * @type {string}
  */
-export const _ICE_ESTABLISHMENT_DURATION = 'establishmentDuration';
+export const TYPE_TRACK = 'track';
 
 /**
- * TODO: document, reformat
- *
- * Known full event names:
- * ice.initiator.gatheringDuration
- * ice.responder.gatheringDuration
- * p2p.ice.initiator.gatheringDuration
- * p2p.ice.responder.gatheringDuration
- *
- * Properties: value
+ * The constant which identifies an event of type "ui".
+ * @type {string}
  */
-export const _ICE_GATHERING_DURATION = 'gatheringDuration';
+export const TYPE_UI = 'ui';
 
 /**
- * TODO: document, reformat
- *
- * Known full event names:
- * audio.no_data_from_source
- * video.no_data_from_source
- */
-export const _NO_DATA_FROM_SOURCE = 'no_data_from_source';
-
-/**
- * TODO: document, reformat
- *
- * Known full event names:
- * audio.track_unmute
- * video.track_unmute
+ * The "action" value for Jingle events which indicates that the Jingle session
+ * was restarted (TODO: verify/fix the documentation)
+ * @type {string}
  */
-export const _TRACK_UNMUTE = 'track_unmute';
+export const ACTION_JINGLE_RESTART = 'restart';
 
 /**
- * TODO: document, reformat
- *
- * TTMF: Time To First Media
- *
- * Known full event names:
- * audio.ttfm
- * video.ttfm
- * audio.ttfm.muted
- * video.ttfm.muted
+ * The "action" value for Jingle events which indicates that a session-accept
+ * timed out (TODO: verify/fix the documentation)
+ * @type {string}
  */
-export const _TTFM_ = 'ttfm';
+export const ACTION_JINGLE_SA_TIMEOUT = 'session-accept.timeout';
 
 /**
- * All average RTP stats are currently reported under 1 event name, but with
- * different properties that allows to distinguish between a P2P call, a
- * call relayed through TURN or the JVB, and multiparty vs 1:1.
- * Example structure of an "avg.rtp.stats" analytics event:
- *
- * {
-     *   p2p: true,
-     *   conferenceSize: 2,
-     *   localCandidateType: "relay",
-     *   remoteCandidateType: "relay",
-     *   transportType: "udp",
-     *
-     *   "stat_avg_rtt": {
-     *     value: 200,
-     *     samples: [ 100, 200, 300 ]
-     *   },
-     *   "stat_avg_packetloss_total": {
-     *     value: 10,
-     *     samples: [ 5, 10, 15]
-     *   }
-     * }
- *
- * Note that the samples array is currently emitted for debug purposes only
- * and can be removed anytime soon from the structure.
- *
- * Also not all values are always present in "avg.rtp.stats", some of the
- * values are obtained and calculated as part of different process/event
- * pipe. For example {@link ConnectionAvgStats} instances are doing the
- * reports for each {@link TraceablePeerConnection} and work independently
- * from the main stats pipe.
+ * The "action" value for Jingle events which indicates that a session-initiate
+ * was received.
+ * @type {string}
  */
-export const AVG_RTP_STATS = 'avg.rtp.stats';
+export const ACTION_JINGLE_SI_RECEIVED = 'session-initiate.received';
 
 /**
- * Properties: none
- *
- * TODO: document, deprecate?
+ * A constant for the "terminate" action for Jingle events. TODO: verify/fix
+ * the documentation)
+ * @type {string}
  */
-export const BRIDGE_DOWN = 'conference.bridgeDown';
+export const ACTION_JINGLE_TERMINATE = 'terminate';
 
 /**
- * Properties: none
- *
- * Known full event names:
- * conference.error.p2pSessionAcceptTimeout
- * conference.error.sessionAcceptTimeout
- *
- * TODO: document, reformat
+ * The "action" value for Jingle events which indicates that a transport-replace
+ * was received.
+ * @type {string}
  */
-export const CONFERENCE_ERROR_ = 'conference.error';
+export const ACTION_JINGLE_TR_RECEIVED
+    = 'transport-replace.received';
 
 /**
- * Properties: none
- *
- * TODO: document
+ * The "action" value for Jingle events which indicates that a transport-replace
+ * succeeded (TODO: verify/fix the documentation)
+ * @type {string}
  */
-export const CONNECTION_INTERRUPTED = 'connection.interrupted';
+export const ACTION_JINGLE_TR_SUCCESS
+    = 'transport-replace.success';
 
 /**
- * Properties: none
- *
- * Known full event names: NONE
- *
- * TODO: document, reformat?, deprecate?
+ * The "action" value for P2P events which indicates that a connection was
+ * established (TODO: verify/fix the documentation)
+ * @type {string}
  */
-export const CONNECTION_DISCONNECTED_ = 'connection.disconnected';
+export const ACTION_P2P_ESTABLISHED = 'established';
 
 /**
- * Properties: label
- *
- * Known full event names:
- * connection.failed.connection.droppedError
- * connection.failed.connection.otherError
- * connection.failed.connection.passwordRequired
- *
- * TODO: document, reformat
+ * The "action" value for P2P events which indicates that something failed.
+ * @type {string}
  */
-export const CONNECTION_FAILED_ = 'connection.failed';
+export const ACTION_P2P_FAILED = 'failed';
 
 /**
- * Properties: none
- *
- * TODO: document
+ * The "action" value for P2P events which indicates that a switch to
+ * jitsi-videobridge happened.
+ * @type {string}
  */
-export const CONNECTION_RESTORED = 'connection.restored';
+export const ACTION_P2P_SWITCH_TO_JVB = 'switch.to.jvb';
 
 /**
- * Properties: value
+ * The name of an event which indicates an available device. We send one such
+ * event per available device once when the available devices are first known,
+ * and every time that they change
+ * @type {string}
  *
- * TODO: document, deprecate (is it the same as the one which is part of
- * CONNECTION_TIMES?)
- */
-export const DATA_CHANNEL_OPEN = 'conference.dataChannel.open';
-
-/**
- * TODO: document, reformat
+ * Properties:
+ *      audio_input_device_count: the number of audio input devices available at
+ *          the time the event was sent.
+ *      audio_output_device_count: the number of audio output devices available
+ *          at the time the event was sent.
+ *      video_input_device_count: the number of video input devices available at
+ *          the time the event was sent.
+ *      video_output_device_count: the number of video output devices available
+ *          at the time the event was sent.
+ *      device_id: an identifier of the device described in this event.
+ *      device_group_id:
+ *      device_kind: one of 'audioinput', 'audiooutput', 'videoinput' or
+ *          'videooutput'.
+ *      device_label: a string which describes the device.
  */
-export const DEVICE_LIST = 'devices.deviceList';
+export const AVAILABLE_DEVICE = 'available.device';
 
 /**
- * User feedback event.
- * Properties: value, detailed
+ * This appears to be fired only in certain cases when the XMPP connection
+ * disconnects (and it was intentional?). It is currently never observed to
+ * fire in production.
  *
  * TODO: document
- */
-export const FEEDBACK = 'feedback.rating';
-
-/**
- * Properties: none
  *
- * TODO: document
+ * Properties:
+ *      message: an error message
  */
-export const FOCUS_LEFT = 'conference.focusLeft';
+export const CONNECTION_DISCONNECTED = 'connection.disconnected';
 
 /**
- * Properties: none
- *
- * Known full event names:
- * getUserMedia.deviceNotFound.audio
- * getUserMedia.deviceNotFound.audio.video
- * getUserMedia.deviceNotFound.video
- * getUserMedia.deviceNotFound.screen
- *
- * TODO: document, reformat, merge with GET_USER_MEDIA_FAILED?
+ * Indicates that the user of the application provided feedback in terms of a
+ * rating (an integer from 1 to 5) and an optional comment.
+ * Properties:
+ *      value: the user's rating (an integer from 1 to 5)
+ *      comment: the user's comment
  */
-export const GET_USER_MEDIA_DEVICE_NOT_FOUND_
-    = 'getUserMedia.deviceNotFound';
+export const FEEDBACK = 'feedback';
 
 /**
- * Properties: none
+ * Indicates the duration of a particular phase of the ICE connectivity
+ * establishment.
  *
- * Known full event names:
- * getUserMedia.fail.resolution.180
- * getUserMedia.fail.resolution.360
- * getUserMedia.fail.resolution.640
- * getUserMedia.fail.resolution.720
- * getUserMedia.fail.resolution.960
- *
- * TODO: reformat, merge with GET_USER_MEDIA_FAILED
+ * Properties:
+ *      phase: the ICE phase (e.g. 'gathering', 'checking', 'establishment')
+ *      value: the duration in milliseconds.
+ *      p2p: whether the associated ICE connection is p2p or towards a
+ *          jitsi-videobridge
+ *      initiator: whether the local Jingle peer is the initiator or responder
+ *          in the Jingle session. XXX we probably actually care about the ICE
+ *          role (controlling vs controlled), and we assume that this correlates
+ *          with the Jingle initiator.
  */
-export const GET_USER_MEDIA_FAIL_ = 'getUserMedia.fail';
+export const ICE_DURATION = 'ice.duration';
 
 /**
- * Properties: value
+ * Indicates the difference in milliseconds between the ICE establishment time
+ * for the P2P and JVB connections (e.g. a value of 10 would indicate that the
+ * P2P connection took 10ms more than JVB connection to establish).
  *
- * Known full event names:
- * getUserMedia.failed.Error
- * getUserMedia.failed.TypeError
- * getUserMedia.failed.audio.TypeError
- * getUserMedia.failed.audio.gum.general
- * getUserMedia.failed.audio.gum.permission_denied
- * getUserMedia.failed.audio.track.no_data_from_source
- * getUserMedia.failed.audio.video.180.gum.general
- * getUserMedia.failed.audio.video.360.gum.general
- * getUserMedia.failed.audio.video.360.gum.permission_denied
- * getUserMedia.failed.audio.video.360.track.no_data_from_source
- * getUserMedia.failed.audio.video.720.TypeError
- * getUserMedia.failed.audio.video.720.gum.constraint_failed
- * getUserMedia.failed.audio.video.720.gum.general
- * getUserMedia.failed.audio.video.720.gum.permission_denied
- * getUserMedia.failed.audio.video.720.track.no_data_from_source
- * getUserMedia.failed.audio.video.960.gum.permission_denied
- * getUserMedia.failed.audio.video.undefined.gum.general
- * getUserMedia.failed.desktop.TypeError
- * getUserMedia.failed.desktop.gum.chrome_extension_generic_error
- * getUserMedia.failed.desktop.gum.chrome_extension_installation_error
- * getUserMedia.failed.desktop.gum.chrome_extension_user_gesture_required
- * getUserMedia.failed.desktop.gum.general
- * getUserMedia.failed.desktop.track.no_data_from_source
- * getUserMedia.failed.gum.chrome_extension_generic_error
- * getUserMedia.failed.gum.chrome_extension_installation_error
- * getUserMedia.failed.gum.constraint_failed
- * getUserMedia.failed.gum.firefox_extension_needed
- * getUserMedia.failed.gum.general
- * getUserMedia.failed.gum.permission_denied
- * getUserMedia.failed.undefined
- * getUserMedia.failed.video.360.gum.permission_denied
- * getUserMedia.failed.video.720.TypeError
- * getUserMedia.failed.video.720.gum.constraint_failed
- * getUserMedia.failed.video.720.gum.general
- * getUserMedia.failed.video.720.gum.permission_denied
- * getUserMedia.failed.video.720.track.no_data_from_source
- * getUserMedia.failed.video.undefined.TypeError
- * getUserMedia.failed.video.undefined.gum.general
- * getUserMedia.failed.video.undefined.track.no_data_from_source
+ * Properties:
+ *      value: the difference in establishment durations in milliseconds.
  *
- * TODO: reformat
  */
-export const GET_USER_MEDIA_FAILED_ = 'getUserMedia.failed';
+export const ICE_ESTABLISHMENT_DURATION_DIFF
+    = 'ice.establishment.duration.diff';
 
 /**
- * Properties: value
- *
- * Known full event names:
- * getUserMedia.success
- * getUserMedia.success.audio
- * getUserMedia.success.audio.video.180
- * getUserMedia.success.audio.video.300
- * getUserMedia.success.audio.video.360
- * getUserMedia.success.audio.video.720
- * getUserMedia.success.audio.video.960
- * getUserMedia.success.audio.video.undefined
- * getUserMedia.success.desktop
- * getUserMedia.success.video.180
- * getUserMedia.success.video.360
- * getUserMedia.success.video.720
- * getUserMedia.success.video.960
- * getUserMedia.success.video.undefined
+ * Indicates that the ICE state has changed.
  *
- * TODO: document, reformat
+ * Properties:
+ *      state: the ICE state which was entered (e.g. 'checking', 'connected',
+ *          'completed', etc).
+ *      value: the time in milliseconds (as reported by
+ *          window.performance.now()) that the state change occurred.
+ *      p2p: whether the associated ICE connection is p2p or towards a
+ *          jitsi-videobridge
+ *      signalingState: The signaling state of the associated PeerConnection
+ *      reconnect: whether the associated Jingle session is in the process of
+ *          reconnecting (or is it ICE? TODO: verify/fix the documentation)
  */
-export const GET_USER_MEDIA_SUCCESS_ = 'getUserMedia.success';
+export const ICE_STATE_CHANGED = 'ice.state.changed';
 
 /**
- * Properties: none
+ * Indicates that a track was unmuted (?).
  *
- * Known full event names:
- * getUserMedia.userCancel.extensionInstall
- *
- * TODO: document, reformat
+ * Properties:
+ *      mediaType: the media type of the local track ('audio' or 'video').
+ *      trackType: the type of the track ('local' or 'remote').
+ *      value: TODO: document
  */
-export const GET_USER_MEDIA_USER_CANCEL_ = 'getUserMedia.userCancel';
+export const TRACK_UNMUTED = 'track.unmuted';
 
 /**
- * Properties: value
- *
- * The "value" property contains the difference in milliseconds between
- * the ICE establishment time for the P2P and JVB connections (e.g. a value
- * of 10 would indicate that the P2P was 10ms slower than JVB).
+ * Creates an operational event which indicates that we have received a
+ * "bridge down" event from jicofo.
  */
-export const ICE_ESTABLISHMENT_DURATION_DIFF
-    = 'ice.establishmentDurationDiff';
+export const createBridgeDownEvent = function() {
+    const bridgeDown = 'bridge.down';
 
-/**
- * Properties: none
- *
- * TODO: document
- * TODO: do we need this in addition to _ICE_CONNECTION_STATE?
- */
-export const ICE_FAILED = 'connection.ice_failed';
+    return {
+        action: bridgeDown,
+        actionSubject: bridgeDown,
+        type: TYPE_OPERATIONAL
+    };
+};
 
 /**
- * Properties: none
- *
- * TODO: document
+ * Creates an event which indicates that the XMPP connection failed
+ * @param errorType TODO
+ * @param errorMessage TODO
  */
-export const P2P_ESTABLISHED = 'p2p.established';
+export const createConnectionFailedEvent = function(errorType, errorMessage) {
+    return {
+        type: TYPE_OPERATIONAL,
+        action: 'connection.failed',
+        attributes: {
+            'error_type': errorType,
+            'error_message': errorMessage
+        }
+    };
+};
 
 /**
- * Properties: none
+ * Creates an operational event which indicates that a particular connection
+ * stage was reached (i.e. the XMPP connection transitioned to the "connected"
+ * state).
  *
- * TODO: document
- */
-export const P2P_FAILED = 'p2p.failed';
-
-/**
- * Properties: none
+ * @param stage the stage which was reached
+ * @param attributes additional attributes for the event. This should be an
+ * object with a "value" property indicating a timestamp in milliseconds
+ * relative to the beginning of the document's lifetime.
  *
- * TODO: document
  */
-export const P2P_SWITCH_TO_JVB = 'p2p.switch_to_jvb';
+export const createConnectionStageReachedEvent = function(stage, attributes) {
+    const action = 'connection.stage.reached';
+
+    return {
+        action,
+        actionSubject: stage,
+        attributes,
+        source: action,
+        type: TYPE_OPERATIONAL
+    };
+};
 
 /**
- * Properties: none
- *
- * TODO: document
+ * Creates an event which indicates that the focus has left the MUC.
  */
-export const REMOTELY_MUTED = 'conference.remotelyMuted';
+export const createFocusLeftEvent = function() {
+    const action = 'focus.left';
+
+    return {
+        action,
+        actionSubject: action,
+        type: TYPE_OPERATIONAL
+    };
+};
 
 /**
- * Properties: value
- *
- * TODO: document
+ * Creates an event related to a getUserMedia call.
  *
- * The "value" property contains the delay in milliseconds between joining
- * the MUC and receiving a Jingle session-initiate from Jicofo (but not
- * P2P).
+ * @param action the type of the result that the event represents: 'error',
+ * 'success', 'warning', etc.
+ * @param attributes the attributes to attach to the event.
+ * @returns {{type: string, source: string, name: string}}
  */
-export const SESSION_INITIATE = 'session.initiate';
+export const createGetUserMediaEvent = function(action, attributes = {}) {
+    return {
+        type: TYPE_OPERATIONAL,
+        source: 'get.user.media',
+        action,
+        attributes
+    };
+};
 
 /**
- * Properties: value
- *
- * TODO: document
+ * Creates an event for a Jingle-related event.
+ * @param action the action of the event
+ * @param attributes attributes to add to the event.
  */
-export const SESSION_INITIATE_RECEIVED = 'xmpp.session-initiate';
+export const createJingleEvent = function(action, attributes = {}) {
+    return {
+        type: TYPE_OPERATIONAL,
+        action,
+        source: 'jingle',
+        attributes
+    };
+};
 
 /**
- * Properties: none
+ * Creates an event which indicates that a local track was not able to read
+ * data from its source (a camera or a microphone).
  *
- * TODO: document
+ * @param mediaType {String} the media type of the local track ('audio' or
+ * 'video').
  */
-export const SESSION_TERMINATE = 'session.terminate';
+export const createNoDataFromSourceEvent = function(mediaType) {
+    return {
+        attributes: { 'media_type': mediaType },
+        action: 'track.no.data.from.source',
+        type: TYPE_OPERATIONAL
+    };
+};
 
 /**
- * Properties: none
- *
- * TODO: document
+ * Creates an event for a p2p-related event.
+ * @param action the action of the event
+ * @param attributes attributes to add to the event.
  */
-export const SESSION_RESTART = 'session.restart';
+export const createP2PEvent = function(action, attributes = {}) {
+    return {
+        type: TYPE_OPERATIONAL,
+        action,
+        source: 'p2p',
+        attributes
+    };
+};
 
 /**
- * Properties: value
- *
- * TODO: document
+ * Indicates that we received a remote command to mute.
  */
-export const TRANSPORT_REPLACE_START = 'xmpp.transport-replace.start';
+export const createRemotelyMutedEvent = function() {
+    return {
+        type: TYPE_OPERATIONAL,
+        action: 'remotely.muted'
+    };
+};
 
 /**
- * Properties: value
+ * Creates an event which contains RTP statistics such as RTT and packet loss.
  *
- * TODO: document
- */
-export const TRANSPORT_REPLACE_SUCCESS = 'xmpp.transport-replace.success';
+ * All average RTP stats are currently reported under 1 event name, but with
+ * different properties that allows to distinguish between a P2P call, a
+ * call relayed through TURN or the JVB, and multiparty vs 1:1.
+ *
+ * The structure of the event is:
+ *
+ * {
+ *      p2p: true,
+ *      conferenceSize: 2,
+ *      localCandidateType: "relay",
+ *      remoteCandidateType: "relay",
+ *      transportType: "udp",
+ *
+ *      // Average RTT of 200ms
+ *      "rtt.avg": 200,
+ *      "rtt.samples": "[100, 200, 300]",
+ *
+ *      // Average packet loss of 10%
+ *      "packet.loss.avg": 10,
+ *      "packet.loss.samples": '[5, 10, 15]'
+ *
+ *      // Difference in milliseconds in the end-to-end RTT between p2p and jvb.
+ *      // The e2e RTT through jvb is 15ms shorter:
+ *      "rtt.diff": 15,
+ *
+ *      // End-to-end RTT through JVB is ms.
+ *      "end2end.rtt.avg" = 100
+ * }
+ *
+ * Note that the value of the "samples" properties are (JSON encoded) strings,
+ * and not JSON arrays, as events' attributes can not be nested. The samples are
+ * currently included for debug purposes only and can be removed anytime soon
+ * from the structure.
+ *
+ * Also note that not all of values are present in each event, as values are
+ * obtained and calculated as part of different process/event pipe. For example
+ * {@link ConnectionAvgStats} instances are doing the reports for each
+ * {@link TraceablePeerConnection} and work independently from the main stats
+ * pipe.
+ */
+export const createRtpStatsEvent = function(attributes) {
+    return {
+        type: TYPE_OPERATIONAL,
+        action: 'rtp.stats',
+        attributes
+    };
+};
+
+/**
+ * Creates an event which indicates the Time To First Media (TTFM).
+ * It is measured in milliseconds relative to the beginning of the document's
+ * lifetime (i.e. the origin used by window.performance.now()), and it excludes
+ * the following:
+ * 1. The delay due to getUserMedia()
+ * 2. The period between the MUC being joined and the reception of the Jingle
+ * session-initiate from jicofo. This is because jicofo will not start a Jingle
+ * session until there are at least 2 participants in the room.
+ *
+ * @param attributes the attributes to add to the event. Currently used fields:
+ *      mediaType: the media type of the local track ('audio' or 'video').
+ *      muted: whether the track has ever been muted (?)
+ *      value: the TTMF in milliseconds.
+ */
+export const createTtfmEvent = function(attributes) {
+    return createConnectionStageReachedEvent('ttfm', attributes);
+};