michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
michael@0:  * You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: this.EXPORTED_SYMBOLS = ["TelemetryTimestamps"];
michael@0: 
michael@0: const Cu = Components.utils;
michael@0: 
michael@0: /**
michael@0:  * This module's purpose is to collect timestamps for important
michael@0:  * application-specific events.
michael@0:  *
michael@0:  * The TelemetryPing component attaches the timestamps stored by this module to
michael@0:  * the telemetry submission, substracting the process lifetime so that the times
michael@0:  * are relative to process startup. The overall goal is to produce a basic
michael@0:  * timeline of the startup process.
michael@0:  */
michael@0: let timeStamps = {};
michael@0: 
michael@0: this.TelemetryTimestamps = {
michael@0:   /**
michael@0:    * Adds a timestamp to the list. The addition of TimeStamps that already have
michael@0:    * a value stored is ignored.
michael@0:    *
michael@0:    * @param name must be a unique, generally "camelCase" descriptor of what the
michael@0:    *             timestamp represents. e.g.: "delayedStartupStarted"
michael@0:    * @param value is a timeStamp in milliseconds since the epoch. If omitted,
michael@0:    *              defaults to Date.now().
michael@0:    */
michael@0:   add: function TT_add(name, value) {
michael@0:     // Default to "now" if not specified
michael@0:     if (value == null)
michael@0:       value = Date.now();
michael@0: 
michael@0:     if (isNaN(value))
michael@0:       throw new Error("Value must be a timestamp");
michael@0: 
michael@0:     // If there's an existing value, just ignore the new value.
michael@0:     if (timeStamps.hasOwnProperty(name))
michael@0:       return;
michael@0: 
michael@0:     timeStamps[name] = value;
michael@0:   },
michael@0: 
michael@0:   /**
michael@0:    * Returns a JS object containing all of the timeStamps as properties (can be
michael@0:    * easily serialized to JSON). Used by TelemetryPing to retrieve the data
michael@0:    * to attach to the telemetry submission.
michael@0:    */
michael@0:   get: function TT_get() {
michael@0:     // Return a copy of the object.
michael@0:     return Cu.cloneInto(timeStamps, {});
michael@0:   }
michael@0: };