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
|
/* -*- 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"
[scriptable, uuid(98d0e975-9cad-4ce3-ae2f-f878b8be6307)]
interface nsIFOG : nsISupports
{
/**
* Initialize FOG.
*
* Call it eventually. Metric data recorded beforehand will be buffered.
*
* @param aDataPathOverride - The path of a custom Glean data path to use
* instead of the profile dir.
* @param aAppIdOverride - The application_id to use instead of
* "firefox.desktop".
* @param aDisableInternalPings - Whether to disable internal pings (baseline, events, metrics).
* Default: false.
*/
void initializeFOG([optional] in AUTF8String aDataPathOverride, [optional] in AUTF8String aAppIdOverride, [optional] in boolean aDisableInternalPings);
/**
* Register custom pings.
*
* Ensure all custom pings are registered with Glean.
*/
void registerCustomPings();
/**
* Enable or Disable the logging of pings in the Glean SDK.
* See https://firefox-source-docs.mozilla.org/toolkit/components/glean/dev/testing.html
* for details.
*
* @param aEnableLogPings - true to enable logging, false to disable.
*/
void setLogPings(in boolean aEnableLogPings);
/**
* Set the tag to be applied to pings assembled from now on.
* See https://firefox-source-docs.mozilla.org/toolkit/components/glean/dev/testing.html
* for details.
*
* @param aDebugTag - The string tag to apply.
* If it cannot be applied (e.g it contains characters that are
* forbidden in HTTP headers) the old value will remain.
*/
void setTagPings(in ACString aDebugTag);
/**
* Send the named ping.
* See https://firefox-source-docs.mozilla.org/toolkit/components/glean/dev/testing.html
* for details.
*
* @param aPingName - The name of the ping to send. If no ping of that name
* exists, or the ping is known but cannot be assembled
* (e.g if it is empty), no ping will be sent.
*/
void sendPing(in ACString aPingName);
/**
* Indicate that an experiment is running.
* Glean will add an experiment annotation which is sent with pings.
* This information is not persisted between runs.
*
* See `glean_core::Glean::set_experiment_active`.
*
* Logs on error, but does not throw.
*
* @param aExperimentId - The id/slug of the experiment.
* @param aBranch - The name of the active branch of the experiment.
* @param aExtra - Optional string -> string dictionary of extra information.
*/
[implicit_jscontext]
void setExperimentActive(in ACString aExperimentId, in ACString aBranch, [optional] in jsval aExtra);
/**
* Indicate that an experiment is no longer running.
*
* See `glean_core::Glean::set_experiment_inactive`.
*
* Logs on error, but does not throw.
*
* @param aExperimentId - The id/slug of the experiment from setExperimentActive.
*/
void setExperimentInactive(in ACString aExperimentId);
/**
* **Test-only API**
*
* If the identified experiment was set active and hasn't been set inactive,
* this will give you the active branch and extra information.
*
* @param aExperimentId - The id/slug of the experiment from setExperimentActive.
*
* @return an object of the form
* {branch: "branch-name", extra: {extra_key1: extra_value1, ...}}
* if there is an active experiment. Undefined, otherwise.
*/
[implicit_jscontext]
jsval testGetExperimentData(in ACString aExperimentId);
/**
* Set remote-configuration for metrics' disabled property.
*
* See [`glean_core::Glean::set_metrics_enabled_config`]
*
* Logs on error, but does not throw.
*
* @param aJsonConfig - The stringified JSON object in the form
* {metric_base_identifier: boolean,}
* which may contain multiple metric object entries.
*/
void applyServerKnobsConfig(in ACString aJsonConfig);
/**
* ** Test-only Method **
*
* Flush all data from all child processes.
*
* @returns A promise that resolves when the data's been stored.
*/
[implicit_jscontext]
Promise testFlushAllChildren();
/**
* ** Test-only Method **
*
* Reset FOG and the Glean SDK, clearing storage.
*/
void testResetFOG([optional] in AUTF8String aDataPathOverride, [optional] in AUTF8String aAppIdOverride);
/**
* ** Test-only Method **
*
* Trigger test metric instrumentation on the GPU, RDD or Socket process.
*
* @param aProcessType - A PROCESS_TYPE_* value from the constants defined
* in the nsIXULRuntime interface.
*
* @returns A promise that resolves when the test data has been added.
* The promise will be rejected if the process type is not supported
* or if sending the IPC to the child process fails.
*/
[implicit_jscontext]
Promise testTriggerMetrics(in unsigned long aProcessType);
/**
* ** Test-only Method **
*
* Register a metric.
*
* This function is deliberately not too friendly to use. You probably aren't
* supposed to use it unless you're testing metric registration itself.
*
* @param aType - The metric's type.
* @param aCategory - The metric's category.
* @param aName - The metric's name.
* @param aPings - The pings to send it in.
* @param aLifetime - The metric's lifetime.
* @param aDisabled - Whether the metric, though existing, isn't enabled.
* @param aExtraArgs - Optional JSON string of extra args.
*/
uint32_t testRegisterRuntimeMetric(in ACString aType,
in ACString aCategory,
in ACString aName,
in Array<ACString> aPings,
in ACString aLifetime,
in boolean aDisabled,
[optional] in ACString aExtraArgs);
/**
* ** Test-only Method **
*
* Register a ping.
*
* This function is deliberately not too friendly to use. You probably aren't
* supposed to use it unless you're testing ping registration itself.
*
* @param aName - The ping's name.
* @param aIncludeClientId - Whether the ping should include the client_id.
* @param aSendIfEmpty - Whether the ping should send even if empty.
* @param aIncludeInfoSections - Whether the ping should include
* {client|ping}_info sections.
* TODO(jer): docs
* @param aReasonCodes - The list of valid reasons for ping submission.
*/
uint32_t testRegisterRuntimePing(in ACString aName,
in boolean aIncludeClientId,
in boolean aSendIfEmpty,
in boolean aPreciseTimestamps,
in boolean aIncludeInfoSections,
in boolean aEnabled,
in Array<ACString> aSchedulesPings,
in Array<ACString> aReasonCodes);
};
|
