DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (d1ed7de67f5a)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315
/* -*- Mode: C++; c-basic-offset: 2; indent-tabs-mode: nil; tab-width: 8 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"
#include "nsIFile.idl"

[scriptable,function, uuid(3d3b9075-5549-4244-9c08-b64fefa1dd60)]
interface nsIFetchTelemetryDataCallback : nsISupports
{
  void complete();
};

[scriptable, uuid(080b55ca-2469-4a61-a230-fc9dac02c2c1)]
interface nsITelemetry : nsISupports
{
  /**
   * Histogram types:
   * HISTOGRAM_EXPONENTIAL - buckets increase exponentially
   * HISTOGRAM_LINEAR - buckets increase linearly
   * HISTOGRAM_BOOLEAN - For storing 0/1 values
   * HISTOGRAM_FLAG - For storing a single value; its count is always == 1.
   * HISTOGRAM_COUNT - For storing counter values without bucketing.
   */
  const unsigned long HISTOGRAM_EXPONENTIAL = 0;
  const unsigned long HISTOGRAM_LINEAR = 1;
  const unsigned long HISTOGRAM_BOOLEAN = 2;
  const unsigned long HISTOGRAM_FLAG = 3;
  const unsigned long HISTOGRAM_COUNT = 4;

  /*
   * An object containing a snapshot from all of the currently registered histograms.
   * { name1: {data1}, name2:{data2}...}
   * where data is consists of the following properties:
   *   min - Minimal bucket size
   *   max - Maximum bucket size
   *   histogram_type - HISTOGRAM_EXPONENTIAL, HISTOGRAM_LINEAR, HISTOGRAM_BOOLEAN
   *                    or HISTOGRAM_COUNT
   *   counts - array representing contents of the buckets in the histogram
   *   ranges -  an array with calculated bucket sizes
   *   sum - sum of the bucket contents
   *   static - true for histograms defined in TelemetryHistograms.h, false for ones defined with newHistogram
   */
  [implicit_jscontext]
  readonly attribute jsval histogramSnapshots;

  /**
   * The amount of time, in milliseconds, that the last session took
   * to shutdown.  Reads as 0 to indicate failure.
   */
  readonly attribute uint32_t lastShutdownDuration;

  /**
   * The number of failed profile lock attempts that have occurred prior to 
   * successfully locking the profile
   */
  readonly attribute uint32_t failedProfileLockCount;

  /*
   * An object containing information about slow SQL statements.
   *
   * {
   *   mainThread: { "sqlString1": [<hit count>, <total time>], "sqlString2": [...], ... },
   *   otherThreads: { "sqlString3": [<hit count>, <total time>], "sqlString4": [...], ... }
   * }
   *
   * where:
   *   mainThread: Slow statements that executed on the main thread
   *   otherThreads: Slow statements that executed on a non-main thread
   *   sqlString - String of the offending statement (see note)
   *   hit count - The number of times this statement required longer than the threshold time to execute
   *   total time - The sum of all execution times above the threshold time for this statement
   *
   * Note that dynamic SQL strings and SQL strings executed against addon DBs could contain private information.
   * This property represents such SQL as aggregate database-level stats and the sqlString contains the database
   * filename instead.
   */
  [implicit_jscontext]
  readonly attribute jsval slowSQL;

  /*
   * See slowSQL above.
   *
   * An object containing full strings of every slow SQL statement if toolkit.telemetry.debugSlowSql = true
   * The returned SQL strings may contain private information and should not be reported to Telemetry.
   */
  [implicit_jscontext]
  readonly attribute jsval debugSlowSQL;

  /**
   * A number representing the highest number of concurrent threads
   * reached during this session.
   */
  readonly attribute uint32_t maximalNumberOfConcurrentThreads;

  /*
   * An array of chrome hang reports. Each element is a hang report represented
   * as an object containing the hang duration, call stack PCs and information
   * about modules in memory.
   */
  [implicit_jscontext]
  readonly attribute jsval chromeHangs;

  /*
   * An array of thread hang stats,
   *   [<thread>, <thread>, ...]
   * <thread> represents a single thread,
   *   {"name": "<name>",
   *    "activity": <time>,
   *    "hangs": [<hang>, <hang>, ...]}
   * <time> represents a histogram of time intervals in milliseconds,
   *   with the same format as histogramSnapshots
   * <hang> represents a particular hang,
   *   {"stack": <stack>, "nativeStack": <stack>, "histogram": <time>}
   * <stack> represents the hang's stack,
   *   ["<frame_0>", "<frame_1>", ...]
   */
  [implicit_jscontext]
  readonly attribute jsval threadHangStats;

  /*
   * An object with two fields: memoryMap and stacks.
   * * memoryMap is a list of loaded libraries.
   * * stacks is a list of stacks. Each stack is a list of pairs of the form
   *   [moduleIndex, offset]. The moduleIndex is an index into the memoryMap and
   *   offset is an offset in the library at memoryMap[moduleIndex].
   * This format is used to make it easier to send the stacks to the
   * symbolication server.
   */
  [implicit_jscontext]
  readonly attribute jsval lateWrites;

  /**
   * Returns an array whose values are the names of histograms defined
   * in Histograms.json.
   */
  void registeredHistograms(out uint32_t count,
                            [retval, array, size_is(count)] out string histograms);

  /**
   * Create and return a histogram.  Parameters:
   *
   * @param name Unique histogram name
   * @param expiration Expiration version
   * @param type - HISTOGRAM_EXPONENTIAL, HISTOGRAM_LINEAR or HISTOGRAM_BOOLEAN
   * @param min - Minimal bucket size
   * @param max - Maximum bucket size
   * @param bucket_count - number of buckets in the histogram.
   * The returned object has the following functions:
   *   add(int) - Adds an int value to the appropriate bucket
   *   snapshot() - Returns a snapshot of the histogram with the same data fields as in histogramSnapshots()
   *   clear() - Zeros out the histogram's buckets and sum
   */
  [implicit_jscontext, optional_argc]
  jsval newHistogram(in ACString name, in ACString expiration,
                     in unsigned long histogram_type,
                     [optional] in uint32_t min,
                     [optional] in uint32_t max,
                     [optional] in uint32_t bucket_count);

  /**
   * Create a histogram using the current state of an existing histogram.  The
   * existing histogram must be registered in TelemetryHistograms.h.
   *
   * @param name Unique histogram name
   * @param existing_name Existing histogram name
   * The returned object has the same functions as a histogram returned from newHistogram.
   */
  [implicit_jscontext]
  jsval histogramFrom(in ACString name, in ACString existing_name);

  /**
   * Same as newHistogram above, but for histograms registered in TelemetryHistograms.h.
   *
   * @param id - unique identifier from TelemetryHistograms.h
   */
  [implicit_jscontext]
  jsval getHistogramById(in ACString id);

  /*
   * An object containing a snapshot from all of the currently registered keyed histograms.
   * { name1: {histogramData1}, name2:{histogramData2}...}
   * where the histogramData is as described in histogramSnapshots.
   */
  [implicit_jscontext]
  readonly attribute jsval keyedHistogramSnapshots;

  /**
   * Create and return a keyed histogram.  Parameters:
   *
   * @param name Unique histogram name
   * @param expiration Expiration version
   * @param type - HISTOGRAM_EXPONENTIAL, HISTOGRAM_LINEAR, HISTOGRAM_BOOLEAN, HISTOGRAM_FLAG or HISTOGRAM_COUNT
   * @param min - Minimal bucket size
   * @param max - Maximum bucket size
   * @param bucket_count - number of buckets in the histogram.
   * The returned object has the following functions:
   *   add(string key, [optional] int) - Add an int value to the histogram for that key. If no histogram for that key exists yet, it is created.
   *   snapshot([optional] string key) - If key is provided, returns a snapshot for the histogram with that key or null. If key is not provided, returns the snapshots of all the registered keys in the form {key1: snapshot1, key2: snapshot2, ...}.
   *   keys() - Returns an array with the string keys of the currently registered histograms
   *   clear() - Clears the registered histograms from this.
   */
  [implicit_jscontext, optional_argc]
  jsval newKeyedHistogram(in ACString name,
                          in ACString expiration,
                          in unsigned long histogram_type,
                          [optional] in uint32_t min,
                          [optional] in uint32_t max,
                          [optional] in uint32_t bucket_count);

  /**
   * Returns an array whose values are the names of histograms defined
   * in Histograms.json.
   */
  void registeredKeyedHistograms(out uint32_t count,
                                 [retval, array, size_is(count)] out string histograms);

  /**
   * Same as newKeyedHistogram above, but for histograms registered in TelemetryHistograms.h.
   *
   * @param id - unique identifier from TelemetryHistograms.h
   * The returned object has the same functions as a histogram returned from newKeyedHistogram.
   */
  [implicit_jscontext]
  jsval getKeyedHistogramById(in ACString id);

  /**
   * Set this to false to disable gathering of telemetry statistics.
   */
  attribute boolean canRecord;

  /**
   * A flag indicating whether Telemetry can submit official results.
   */
  readonly attribute boolean canSend;

  /** Addon telemetry hooks */

  /**
   * Register a histogram for an addon.  Throws an error if the
   * histogram name has been registered previously.
   *
   * @param addon_id - Unique ID of the addon
   * @param name - Unique histogram name
   * @param min - Minimal bucket size
   * @param max - Maximum bucket size
   * @param bucket_count - number of buckets in the histogram
   * @param histogram_type - HISTOGRAM_EXPONENTIAL, HISTOGRAM_LINEAR,
   *        HISTOGRAM_BOOLEAN or HISTOGRAM_COUNT
   */
  void registerAddonHistogram(in ACString addon_id, in ACString name,
                              in uint32_t min, in uint32_t max,
                              in uint32_t bucket_count,
                              in unsigned long histogram_type);

  /**
   * Return a histogram previously registered via
   * registerAddonHistogram.  Throws an error if the id/name combo has
   * not been registered via registerAddonHistogram.
   *
   * @param addon_id - Unique ID of the addon
   * @param name - Registered histogram name
   *
   * The returned object has the same functions as a histogram returned
   * from newHistogram.
   */
  [implicit_jscontext]
  jsval getAddonHistogram(in ACString addon_id, in ACString name);

  /**
   * Delete all histograms associated with the given addon id.
   *
   * @param addon_id - Unique ID of the addon
   */
  void unregisterAddonHistograms(in ACString addon_id);

  /**
   * An object containing a snapshot from all of the currently
   * registered addon histograms.
   * { addon-id1 : data1, ... }
   *
   * where data is an object whose properties are the names of the
   * addon's histograms and whose corresponding values are as in
   * histogramSnapshots.
   */
  [implicit_jscontext]
  readonly attribute jsval addonHistogramSnapshots;

  /**
   * Read data from the previous run. After the callback is called, the last
   * shutdown time is available in lastShutdownDuration and any late
   * writes in lateWrites.
   */
  void asyncFetchTelemetryData(in nsIFetchTelemetryDataCallback aCallback);

  /**
   * Get statistics of file IO reports, null, if not recorded.
   *
   * The statistics are returned as an object whose propoerties are the names
   * of the files that have been accessed and whose corresponding values are
   * arrays of size three, representing startup, normal, and shutdown stages.
   * Each stage's entry is either null or an array with the layout
   * [total_time, #creates, #reads, #writes, #fsyncs, #stats]
   */
  [implicit_jscontext]
  readonly attribute jsval fileIOReports;

  /**
   * Return the number of seconds since process start using monotonic
   * timestamps (unaffected by system clock changes).
   * @throws NS_ERROR_NOT_AVAILABLE if TimeStamp doesn't have the data.
   */
  double msSinceProcessStart();
};