1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/toolkit/components/telemetry/nsITelemetry.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,261 @@
1.4 +/* -*- Mode: C++; c-basic-offset: 2; indent-tabs-mode: nil; tab-width: 8 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +#include "nsIFile.idl"
1.11 +
1.12 +[scriptable,function, uuid(3d3b9075-5549-4244-9c08-b64fefa1dd60)]
1.13 +interface nsIFetchTelemetryDataCallback : nsISupports
1.14 +{
1.15 + void complete();
1.16 +};
1.17 +
1.18 +[scriptable, uuid(4e4bfc35-dac6-4b28-ade4-7e45760051d5)]
1.19 +interface nsITelemetry : nsISupports
1.20 +{
1.21 + /**
1.22 + * Histogram types:
1.23 + * HISTOGRAM_EXPONENTIAL - buckets increase exponentially
1.24 + * HISTOGRAM_LINEAR - buckets increase linearly
1.25 + * HISTOGRAM_BOOLEAN - For storing 0/1 values
1.26 + * HISTOGRAM_FLAG - For storing a single value; its count is always == 1.
1.27 + */
1.28 + const unsigned long HISTOGRAM_EXPONENTIAL = 0;
1.29 + const unsigned long HISTOGRAM_LINEAR = 1;
1.30 + const unsigned long HISTOGRAM_BOOLEAN = 2;
1.31 + const unsigned long HISTOGRAM_FLAG = 3;
1.32 +
1.33 + /*
1.34 + * An object containing a snapshot from all of the currently registered histograms.
1.35 + * { name1: {data1}, name2:{data2}...}
1.36 + * where data is consists of the following properties:
1.37 + * min - Minimal bucket size
1.38 + * max - Maximum bucket size
1.39 + * histogram_type - HISTOGRAM_EXPONENTIAL, HISTOGRAM_LINEAR, or HISTOGRAM_BOOLEAN
1.40 + * counts - array representing contents of the buckets in the histogram
1.41 + * ranges - an array with calculated bucket sizes
1.42 + * sum - sum of the bucket contents
1.43 + * static - true for histograms defined in TelemetryHistograms.h, false for ones defined with newHistogram
1.44 + */
1.45 + [implicit_jscontext]
1.46 + readonly attribute jsval histogramSnapshots;
1.47 +
1.48 + /**
1.49 + * The amount of time, in milliseconds, that the last session took
1.50 + * to shutdown. Reads as 0 to indicate failure.
1.51 + */
1.52 + readonly attribute uint32_t lastShutdownDuration;
1.53 +
1.54 + /**
1.55 + * The number of failed profile lock attempts that have occurred prior to
1.56 + * successfully locking the profile
1.57 + */
1.58 + readonly attribute uint32_t failedProfileLockCount;
1.59 +
1.60 + /*
1.61 + * An object containing information about slow SQL statements.
1.62 + *
1.63 + * {
1.64 + * mainThread: { "sqlString1": [<hit count>, <total time>], "sqlString2": [...], ... },
1.65 + * otherThreads: { "sqlString3": [<hit count>, <total time>], "sqlString4": [...], ... }
1.66 + * }
1.67 + *
1.68 + * where:
1.69 + * mainThread: Slow statements that executed on the main thread
1.70 + * otherThreads: Slow statements that executed on a non-main thread
1.71 + * sqlString - String of the offending statement (see note)
1.72 + * hit count - The number of times this statement required longer than the threshold time to execute
1.73 + * total time - The sum of all execution times above the threshold time for this statement
1.74 + *
1.75 + * Note that dynamic SQL strings and SQL strings executed against addon DBs could contain private information.
1.76 + * This property represents such SQL as aggregate database-level stats and the sqlString contains the database
1.77 + * filename instead.
1.78 + */
1.79 + [implicit_jscontext]
1.80 + readonly attribute jsval slowSQL;
1.81 +
1.82 + /*
1.83 + * See slowSQL above.
1.84 + *
1.85 + * An object containing full strings of every slow SQL statement if toolkit.telemetry.debugSlowSql = true
1.86 + * The returned SQL strings may contain private information and should not be reported to Telemetry.
1.87 + */
1.88 + [implicit_jscontext]
1.89 + readonly attribute jsval debugSlowSQL;
1.90 +
1.91 + /**
1.92 + * A number representing the highest number of concurrent threads
1.93 + * reached during this session.
1.94 + */
1.95 + readonly attribute uint32_t maximalNumberOfConcurrentThreads;
1.96 +
1.97 + /*
1.98 + * An array of chrome hang reports. Each element is a hang report represented
1.99 + * as an object containing the hang duration, call stack PCs and information
1.100 + * about modules in memory.
1.101 + */
1.102 + [implicit_jscontext]
1.103 + readonly attribute jsval chromeHangs;
1.104 +
1.105 + /*
1.106 + * An array of thread hang stats,
1.107 + * [<thread>, <thread>, ...]
1.108 + * <thread> represents a single thread,
1.109 + * {"name": "<name>",
1.110 + * "activity": <time>,
1.111 + * "hangs": [<hang>, <hang>, ...]}
1.112 + * <time> represents a histogram of time intervals in milliseconds,
1.113 + * with the same format as histogramSnapshots
1.114 + * <hang> represents a particular hang,
1.115 + * {"stack": <stack>, "histogram": <time>}
1.116 + * <stack> represents the hang's stack,
1.117 + * ["<frame_0>", "<frame_1>", ...]
1.118 + */
1.119 + [implicit_jscontext]
1.120 + readonly attribute jsval threadHangStats;
1.121 +
1.122 + /*
1.123 + * An object with two fields: memoryMap and stacks.
1.124 + * * memoryMap is a list of loaded libraries.
1.125 + * * stacks is a list of stacks. Each stack is a list of pairs of the form
1.126 + * [moduleIndex, offset]. The moduleIndex is an index into the memoryMap and
1.127 + * offset is an offset in the library at memoryMap[moduleIndex].
1.128 + * This format is used to make it easier to send the stacks to the
1.129 + * symbolication server.
1.130 + */
1.131 + [implicit_jscontext]
1.132 + readonly attribute jsval lateWrites;
1.133 +
1.134 + /**
1.135 + * Returns an array whose values are the names of histograms defined
1.136 + * in Histograms.json.
1.137 + */
1.138 + void registeredHistograms(out uint32_t count,
1.139 + [retval, array, size_is(count)] out string histograms);
1.140 +
1.141 + /**
1.142 + * Create and return a histogram. Parameters:
1.143 + *
1.144 + * @param name Unique histogram name
1.145 + * @param expiration Expiration version
1.146 + * @param min - Minimal bucket size
1.147 + * @param max - Maximum bucket size
1.148 + * @param bucket_count - number of buckets in the histogram.
1.149 + * @param type - HISTOGRAM_EXPONENTIAL, HISTOGRAM_LINEAR or HISTOGRAM_BOOLEAN
1.150 + * The returned object has the following functions:
1.151 + * add(int) - Adds an int value to the appropriate bucket
1.152 + * snapshot() - Returns a snapshot of the histogram with the same data fields as in histogramSnapshots()
1.153 + * clear() - Zeros out the histogram's buckets and sum
1.154 + */
1.155 + [implicit_jscontext]
1.156 + jsval newHistogram(in ACString name, in ACString expiration, in uint32_t min, in uint32_t max, in uint32_t bucket_count, in unsigned long histogram_type);
1.157 +
1.158 + /**
1.159 + * Create a histogram using the current state of an existing histogram. The
1.160 + * existing histogram must be registered in TelemetryHistograms.h.
1.161 + *
1.162 + * @param name Unique histogram name
1.163 + * @param existing_name Existing histogram name
1.164 + * The returned object has the same functions as a histogram returned from newHistogram.
1.165 + */
1.166 + [implicit_jscontext]
1.167 + jsval histogramFrom(in ACString name, in ACString existing_name);
1.168 +
1.169 + /**
1.170 + * Same as newHistogram above, but for histograms registered in TelemetryHistograms.h.
1.171 + *
1.172 + * @param id - unique identifier from TelemetryHistograms.h
1.173 + */
1.174 + [implicit_jscontext]
1.175 + jsval getHistogramById(in ACString id);
1.176 +
1.177 + /**
1.178 + * Set this to false to disable gathering of telemetry statistics.
1.179 + */
1.180 + attribute boolean canRecord;
1.181 +
1.182 + /**
1.183 + * A flag indicating whether Telemetry can submit official results.
1.184 + */
1.185 + readonly attribute boolean canSend;
1.186 +
1.187 + /** Addon telemetry hooks */
1.188 +
1.189 + /**
1.190 + * Register a histogram for an addon. Throws an error if the
1.191 + * histogram name has been registered previously.
1.192 + *
1.193 + * @param addon_id - Unique ID of the addon
1.194 + * @param name - Unique histogram name
1.195 + * @param min - Minimal bucket size
1.196 + * @param max - Maximum bucket size
1.197 + * @param bucket_count - number of buckets in the histogram
1.198 + * @param histogram_type - HISTOGRAM_EXPONENTIAL, HISTOGRAM_LINEAR, or
1.199 + * HISTOGRAM_BOOLEAN
1.200 + */
1.201 + void registerAddonHistogram(in ACString addon_id, in ACString name,
1.202 + in uint32_t min, in uint32_t max,
1.203 + in uint32_t bucket_count,
1.204 + in unsigned long histogram_type);
1.205 +
1.206 + /**
1.207 + * Return a histogram previously registered via
1.208 + * registerAddonHistogram. Throws an error if the id/name combo has
1.209 + * not been registered via registerAddonHistogram.
1.210 + *
1.211 + * @param addon_id - Unique ID of the addon
1.212 + * @param name - Registered histogram name
1.213 + *
1.214 + * The returned object has the same functions as a histogram returned
1.215 + * from newHistogram.
1.216 + */
1.217 + [implicit_jscontext]
1.218 + jsval getAddonHistogram(in ACString addon_id, in ACString name);
1.219 +
1.220 + /**
1.221 + * Delete all histograms associated with the given addon id.
1.222 + *
1.223 + * @param addon_id - Unique ID of the addon
1.224 + */
1.225 + void unregisterAddonHistograms(in ACString addon_id);
1.226 +
1.227 + /**
1.228 + * An object containing a snapshot from all of the currently
1.229 + * registered addon histograms.
1.230 + * { addon-id1 : data1, ... }
1.231 + *
1.232 + * where data is an object whose properties are the names of the
1.233 + * addon's histograms and whose corresponding values are as in
1.234 + * histogramSnapshots.
1.235 + */
1.236 + [implicit_jscontext]
1.237 + readonly attribute jsval addonHistogramSnapshots;
1.238 +
1.239 + /**
1.240 + * Read data from the previous run. After the callback is called, the last
1.241 + * shutdown time is available in lastShutdownDuration and any late
1.242 + * writes in lateWrites.
1.243 + */
1.244 + void asyncFetchTelemetryData(in nsIFetchTelemetryDataCallback aCallback);
1.245 +
1.246 + /**
1.247 + * Get statistics of file IO reports, null, if not recorded.
1.248 + *
1.249 + * The statistics are returned as an object whose propoerties are the names
1.250 + * of the files that have been accessed and whose corresponding values are
1.251 + * arrays of size three, representing startup, normal, and shutdown stages.
1.252 + * Each stage's entry is either null or an array with the layout
1.253 + * [total_time, #creates, #reads, #writes, #fsyncs, #stats]
1.254 + */
1.255 + [implicit_jscontext]
1.256 + readonly attribute jsval fileIOReports;
1.257 +
1.258 + /**
1.259 + * Return the number of seconds since process start using monotonic
1.260 + * timestamps (unaffected by system clock changes).
1.261 + * @throws NS_ERROR_NOT_AVAILABLE if TimeStamp doesn't have the data.
1.262 + */
1.263 + double msSinceProcessStart();
1.264 +};
