1.. _buildtelemetry:
2
3===============
4Build Telemetry
5===============
6
7The build system (specifically, all the build tooling hooked
8up to ``./mach``) has been configured to collect metrics data
9points for various build system actions. This data helps drive
10team planning for the build team and ensure that resources are
11applied to build processes that need them most. You can opt-in
12to send telemetry to Mozilla during `./mach bootstrap`.
13
14The build telemetry schema can be found in-tree under
15``python/mozbuild/mozbuild/telemetry.py`` in Voluptuous schema
16format. You can use the ``export_telemetry_schema.py`` script in
17that same directory to get the schema in JSON-schema format.
18Details of the schema are specified below:
19
20
21
22.. _telemetry.json#/:
23
24telemetry
25=========
26
27:type: ``object``
28
29:Required: :ref:`telemetry.json#/properties/argv`, :ref:`telemetry.json#/properties/build_opts`, :ref:`telemetry.json#/properties/client_id`, :ref:`telemetry.json#/properties/command`, :ref:`telemetry.json#/properties/duration_ms`, :ref:`telemetry.json#/properties/success`, :ref:`telemetry.json#/properties/system`, :ref:`telemetry.json#/properties/time`
30
31**Properties:** :ref:`telemetry.json#/properties/argv`, :ref:`telemetry.json#/properties/build_opts`, :ref:`telemetry.json#/properties/client_id`, :ref:`telemetry.json#/properties/command`, :ref:`telemetry.json#/properties/duration_ms`, :ref:`telemetry.json#/properties/exception`, :ref:`telemetry.json#/properties/file_types_changed`, :ref:`telemetry.json#/properties/success`, :ref:`telemetry.json#/properties/system`, :ref:`telemetry.json#/properties/time`
32
33
34.. _telemetry.json#/properties/argv:
35
36argv
37++++
38
39Full mach commandline. If the commandline contains absolute paths they will be sanitized.
40
41:type: ``array``
42
43.. container:: sub-title
44
45 Every element of **argv**  is:
46
47:type: ``string``
48
49
50.. _telemetry.json#/properties/build_opts:
51
52build_opts
53++++++++++
54
55Selected build options
56
57:type: ``object``
58
59**Properties:** :ref:`telemetry.json#/properties/build_opts/properties/artifact`, :ref:`telemetry.json#/properties/build_opts/properties/ccache`, :ref:`telemetry.json#/properties/build_opts/properties/compiler`, :ref:`telemetry.json#/properties/build_opts/properties/debug`, :ref:`telemetry.json#/properties/build_opts/properties/icecream`, :ref:`telemetry.json#/properties/build_opts/properties/opt`, :ref:`telemetry.json#/properties/build_opts/properties/sccache`
60
61
62.. _telemetry.json#/properties/build_opts/properties/artifact:
63
64artifact
65########
66
67true if --enable-artifact-builds
68
69:type: ``boolean``
70
71
72.. _telemetry.json#/properties/build_opts/properties/ccache:
73
74ccache
75######
76
77true if ccache is in use (--with-ccache)
78
79:type: ``boolean``
80
81
82.. _telemetry.json#/properties/build_opts/properties/compiler:
83
84compiler
85########
86
87The compiler type in use (CC_TYPE)
88
89**Allowed values:**
90
91- clang
92- clang-cl
93- gcc
94- msvc
95
96
97.. _telemetry.json#/properties/build_opts/properties/debug:
98
99debug
100#####
101
102true if build is debug (--enable-debug)
103
104:type: ``boolean``
105
106
107.. _telemetry.json#/properties/build_opts/properties/icecream:
108
109icecream
110########
111
112true if icecream in use
113
114:type: ``boolean``
115
116
117.. _telemetry.json#/properties/build_opts/properties/opt:
118
119opt
120###
121
122true if build is optimized (--enable-optimize)
123
124:type: ``boolean``
125
126
127.. _telemetry.json#/properties/build_opts/properties/sccache:
128
129sccache
130#######
131
132true if ccache in use is sccache
133
134:type: ``boolean``
135
136
137.. _telemetry.json#/properties/build_attrs:
138
139build_attrs
140+++++++++++
141
142Selected runtime attributes of the build
143
144:type: ``object``
145
146**Properties:** :ref:`telemetry.json#/properties/build_attrs/properties/cpu_percent`, :ref:`telemetry.json#/properties/build_attrs/properties/clobber`
147
148.. _telemetry.json#/properties/build_attrs/properties/cpu_percent:
149
150cpu_percent
151###########
152
153cpu utilization observed during the build
154
155:type: ``number``
156
157.. _telemetry.json#/properties/build_attrs/properties/clobber:
158
159clobber
160#######
161
162true if the build was a clobber/full build
163
164:type: ``boolean``
165
166
167.. _telemetry.json#/properties/client_id:
168
169client_id
170+++++++++
171
172A UUID to uniquely identify a client
173
174:type: ``string``
175
176
177.. _telemetry.json#/properties/command:
178
179command
180+++++++
181
182The mach command that was invoked
183
184:type: ``string``
185
186
187.. _telemetry.json#/properties/duration_ms:
188
189duration_ms
190+++++++++++
191
192Command duration in milliseconds
193
194:type: ``number``
195
196
197.. _telemetry.json#/properties/exception:
198
199exception
200+++++++++
201
202If a Python exception was encountered during the execution of the command, this value contains the result of calling `repr` on the exception object.
203
204:type: ``string``
205
206
207.. _telemetry.json#/properties/file_types_changed:
208
209file_types_changed
210++++++++++++++++++
211
212This array contains a list of objects with {ext, count} properties giving the count of files changed since the last invocation grouped by file type
213
214:type: ``array``
215
216.. container:: sub-title
217
218 Every element of **file_types_changed**  is:
219
220:type: ``object``
221
222:Required: :ref:`telemetry.json#/properties/file_types_changed/items/properties/count`, :ref:`telemetry.json#/properties/file_types_changed/items/properties/ext`
223
224**Properties:** :ref:`telemetry.json#/properties/file_types_changed/items/properties/count`, :ref:`telemetry.json#/properties/file_types_changed/items/properties/ext`
225
226
227.. _telemetry.json#/properties/file_types_changed/items/properties/count:
228
229count
230#####
231
232Count of changed files with this extension
233
234:type: ``number``
235
236
237.. _telemetry.json#/properties/file_types_changed/items/properties/ext:
238
239ext
240###
241
242File extension
243
244:type: ``string``
245
246
247.. _telemetry.json#/properties/success:
248
249success
250+++++++
251
252true if the command succeeded
253
254:type: ``boolean``
255
256
257.. _telemetry.json#/properties/system:
258
259system
260++++++
261
262:type: ``object``
263
264:Required: :ref:`telemetry.json#/properties/system/properties/os`
265
266**Properties:** :ref:`telemetry.json#/properties/system/properties/cpu_brand`, :ref:`telemetry.json#/properties/system/properties/drive_is_ssd`, :ref:`telemetry.json#/properties/system/properties/logical_cores`, :ref:`telemetry.json#/properties/system/properties/memory_gb`, :ref:`telemetry.json#/properties/system/properties/os`, :ref:`telemetry.json#/properties/system/properties/physical_cores`, :ref:`telemetry.json#/properties/system/properties/virtual_machine`
267
268
269.. _telemetry.json#/properties/system/properties/cpu_brand:
270
271cpu_brand
272#########
273
274CPU brand string from CPUID
275
276:type: ``string``
277
278
279.. _telemetry.json#/properties/system/properties/drive_is_ssd:
280
281drive_is_ssd
282############
283
284true if the source directory is on a solid-state disk
285
286:type: ``boolean``
287
288
289.. _telemetry.json#/properties/system/properties/logical_cores:
290
291logical_cores
292#############
293
294Number of logical CPU cores present
295
296:type: ``number``
297
298
299.. _telemetry.json#/properties/system/properties/memory_gb:
300
301memory_gb
302#########
303
304System memory in GB
305
306:type: ``number``
307
308
309.. _telemetry.json#/properties/system/properties/os:
310
311os
312##
313
314Operating system
315
316**Allowed values:**
317
318- windows
319- macos
320- linux
321- other
322
323
324.. _telemetry.json#/properties/system/properties/physical_cores:
325
326physical_cores
327##############
328
329Number of physical CPU cores present
330
331:type: ``number``
332
333
334.. _telemetry.json#/properties/system/properties/virtual_machine:
335
336virtual_machine
337###############
338
339true if the OS appears to be running in a virtual machine
340
341:type: ``boolean``
342
343
344.. _telemetry.json#/properties/time:
345
346time
347++++
348
349Time at which this event happened
350
351:type: ``string``
352
353:format: ``date-time``
354