toolkit/components/telemetry/nsITelemetry.idl@b8a032363ba2
toolkit/components/telemetry/nsITelemetry.idl
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
1 /* -*- Mode: C++; c-basic-offset: 2; indent-tabs-mode: nil; tab-width: 8 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #include "nsISupports.idl"
7 #include "nsIFile.idl"
9 [scriptable,function, uuid(3d3b9075-5549-4244-9c08-b64fefa1dd60)]
10 interface nsIFetchTelemetryDataCallback : nsISupports
11 {
12 void complete();
13 };
15 [scriptable, uuid(4e4bfc35-dac6-4b28-ade4-7e45760051d5)]
16 interface nsITelemetry : nsISupports
17 {
18 /**
19 * Histogram types:
20 * HISTOGRAM_EXPONENTIAL - buckets increase exponentially
21 * HISTOGRAM_LINEAR - buckets increase linearly
22 * HISTOGRAM_BOOLEAN - For storing 0/1 values
23 * HISTOGRAM_FLAG - For storing a single value; its count is always == 1.
24 */
25 const unsigned long HISTOGRAM_EXPONENTIAL = 0;
26 const unsigned long HISTOGRAM_LINEAR = 1;
27 const unsigned long HISTOGRAM_BOOLEAN = 2;
28 const unsigned long HISTOGRAM_FLAG = 3;
30 /*
31 * An object containing a snapshot from all of the currently registered histograms.
32 * { name1: {data1}, name2:{data2}...}
33 * where data is consists of the following properties:
34 * min - Minimal bucket size
35 * max - Maximum bucket size
36 * histogram_type - HISTOGRAM_EXPONENTIAL, HISTOGRAM_LINEAR, or HISTOGRAM_BOOLEAN
37 * counts - array representing contents of the buckets in the histogram
38 * ranges - an array with calculated bucket sizes
39 * sum - sum of the bucket contents
40 * static - true for histograms defined in TelemetryHistograms.h, false for ones defined with newHistogram
41 */
42 [implicit_jscontext]
43 readonly attribute jsval histogramSnapshots;
45 /**
46 * The amount of time, in milliseconds, that the last session took
47 * to shutdown. Reads as 0 to indicate failure.
48 */
49 readonly attribute uint32_t lastShutdownDuration;
51 /**
52 * The number of failed profile lock attempts that have occurred prior to
53 * successfully locking the profile
54 */
55 readonly attribute uint32_t failedProfileLockCount;
57 /*
58 * An object containing information about slow SQL statements.
59 *
60 * {
61 * mainThread: { "sqlString1": [<hit count>, <total time>], "sqlString2": [...], ... },
62 * otherThreads: { "sqlString3": [<hit count>, <total time>], "sqlString4": [...], ... }
63 * }
64 *
65 * where:
66 * mainThread: Slow statements that executed on the main thread
67 * otherThreads: Slow statements that executed on a non-main thread
68 * sqlString - String of the offending statement (see note)
69 * hit count - The number of times this statement required longer than the threshold time to execute
70 * total time - The sum of all execution times above the threshold time for this statement
71 *
72 * Note that dynamic SQL strings and SQL strings executed against addon DBs could contain private information.
73 * This property represents such SQL as aggregate database-level stats and the sqlString contains the database
74 * filename instead.
75 */
76 [implicit_jscontext]
77 readonly attribute jsval slowSQL;
79 /*
80 * See slowSQL above.
81 *
82 * An object containing full strings of every slow SQL statement if toolkit.telemetry.debugSlowSql = true
83 * The returned SQL strings may contain private information and should not be reported to Telemetry.
84 */
85 [implicit_jscontext]
86 readonly attribute jsval debugSlowSQL;
88 /**
89 * A number representing the highest number of concurrent threads
90 * reached during this session.
91 */
92 readonly attribute uint32_t maximalNumberOfConcurrentThreads;
94 /*
95 * An array of chrome hang reports. Each element is a hang report represented
96 * as an object containing the hang duration, call stack PCs and information
97 * about modules in memory.
98 */
99 [implicit_jscontext]
100 readonly attribute jsval chromeHangs;
102 /*
103 * An array of thread hang stats,
104 * [<thread>, <thread>, ...]
105 * <thread> represents a single thread,
106 * {"name": "<name>",
107 * "activity": <time>,
108 * "hangs": [<hang>, <hang>, ...]}
109 * <time> represents a histogram of time intervals in milliseconds,
110 * with the same format as histogramSnapshots
111 * <hang> represents a particular hang,
112 * {"stack": <stack>, "histogram": <time>}
113 * <stack> represents the hang's stack,
114 * ["<frame_0>", "<frame_1>", ...]
115 */
116 [implicit_jscontext]
117 readonly attribute jsval threadHangStats;
119 /*
120 * An object with two fields: memoryMap and stacks.
121 * * memoryMap is a list of loaded libraries.
122 * * stacks is a list of stacks. Each stack is a list of pairs of the form
123 * [moduleIndex, offset]. The moduleIndex is an index into the memoryMap and
124 * offset is an offset in the library at memoryMap[moduleIndex].
125 * This format is used to make it easier to send the stacks to the
126 * symbolication server.
127 */
128 [implicit_jscontext]
129 readonly attribute jsval lateWrites;
131 /**
132 * Returns an array whose values are the names of histograms defined
133 * in Histograms.json.
134 */
135 void registeredHistograms(out uint32_t count,
136 [retval, array, size_is(count)] out string histograms);
138 /**
139 * Create and return a histogram. Parameters:
140 *
141 * @param name Unique histogram name
142 * @param expiration Expiration version
143 * @param min - Minimal bucket size
144 * @param max - Maximum bucket size
145 * @param bucket_count - number of buckets in the histogram.
146 * @param type - HISTOGRAM_EXPONENTIAL, HISTOGRAM_LINEAR or HISTOGRAM_BOOLEAN
147 * The returned object has the following functions:
148 * add(int) - Adds an int value to the appropriate bucket
149 * snapshot() - Returns a snapshot of the histogram with the same data fields as in histogramSnapshots()
150 * clear() - Zeros out the histogram's buckets and sum
151 */
152 [implicit_jscontext]
153 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);
155 /**
156 * Create a histogram using the current state of an existing histogram. The
157 * existing histogram must be registered in TelemetryHistograms.h.
158 *
159 * @param name Unique histogram name
160 * @param existing_name Existing histogram name
161 * The returned object has the same functions as a histogram returned from newHistogram.
162 */
163 [implicit_jscontext]
164 jsval histogramFrom(in ACString name, in ACString existing_name);
166 /**
167 * Same as newHistogram above, but for histograms registered in TelemetryHistograms.h.
168 *
169 * @param id - unique identifier from TelemetryHistograms.h
170 */
171 [implicit_jscontext]
172 jsval getHistogramById(in ACString id);
174 /**
175 * Set this to false to disable gathering of telemetry statistics.
176 */
177 attribute boolean canRecord;
179 /**
180 * A flag indicating whether Telemetry can submit official results.
181 */
182 readonly attribute boolean canSend;
184 /** Addon telemetry hooks */
186 /**
187 * Register a histogram for an addon. Throws an error if the
188 * histogram name has been registered previously.
189 *
190 * @param addon_id - Unique ID of the addon
191 * @param name - Unique histogram name
192 * @param min - Minimal bucket size
193 * @param max - Maximum bucket size
194 * @param bucket_count - number of buckets in the histogram
195 * @param histogram_type - HISTOGRAM_EXPONENTIAL, HISTOGRAM_LINEAR, or
196 * HISTOGRAM_BOOLEAN
197 */
198 void registerAddonHistogram(in ACString addon_id, in ACString name,
199 in uint32_t min, in uint32_t max,
200 in uint32_t bucket_count,
201 in unsigned long histogram_type);
203 /**
204 * Return a histogram previously registered via
205 * registerAddonHistogram. Throws an error if the id/name combo has
206 * not been registered via registerAddonHistogram.
207 *
208 * @param addon_id - Unique ID of the addon
209 * @param name - Registered histogram name
210 *
211 * The returned object has the same functions as a histogram returned
212 * from newHistogram.
213 */
214 [implicit_jscontext]
215 jsval getAddonHistogram(in ACString addon_id, in ACString name);
217 /**
218 * Delete all histograms associated with the given addon id.
219 *
220 * @param addon_id - Unique ID of the addon
221 */
222 void unregisterAddonHistograms(in ACString addon_id);
224 /**
225 * An object containing a snapshot from all of the currently
226 * registered addon histograms.
227 * { addon-id1 : data1, ... }
228 *
229 * where data is an object whose properties are the names of the
230 * addon's histograms and whose corresponding values are as in
231 * histogramSnapshots.
232 */
233 [implicit_jscontext]
234 readonly attribute jsval addonHistogramSnapshots;
236 /**
237 * Read data from the previous run. After the callback is called, the last
238 * shutdown time is available in lastShutdownDuration and any late
239 * writes in lateWrites.
240 */
241 void asyncFetchTelemetryData(in nsIFetchTelemetryDataCallback aCallback);
243 /**
244 * Get statistics of file IO reports, null, if not recorded.
245 *
246 * The statistics are returned as an object whose propoerties are the names
247 * of the files that have been accessed and whose corresponding values are
248 * arrays of size three, representing startup, normal, and shutdown stages.
249 * Each stage's entry is either null or an array with the layout
250 * [total_time, #creates, #reads, #writes, #fsyncs, #stats]
251 */
252 [implicit_jscontext]
253 readonly attribute jsval fileIOReports;
255 /**
256 * Return the number of seconds since process start using monotonic
257 * timestamps (unaffected by system clock changes).
258 * @throws NS_ERROR_NOT_AVAILABLE if TimeStamp doesn't have the data.
259 */
260 double msSinceProcessStart();
261 };
