OLD | NEW |
1 // This code was auto-generated, is not intended to be edited, and is subject to | 1 // This code was auto-generated, is not intended to be edited, and is subject to |
2 // significant change. Please see the README file for more information. | 2 // significant change. Please see the README file for more information. |
3 | 3 |
4 library engine.instrumentation; | 4 library engine.instrumentation; |
5 | 5 |
6 import 'java_core.dart'; | 6 import 'java_core.dart'; |
7 | 7 |
| 8 |
8 /** | 9 /** |
9 * The class {@code Instrumentation} implements support for logging instrumentat
ion information. | 10 * The class {@code Instrumentation} implements support for logging instrumentat
ion information. |
10 * <p> | 11 * <p> |
11 * Instrumentation information consists of information about specific operations
. Those operations | 12 * Instrumentation information consists of information about specific operations
. Those operations |
12 * can range from user-facing operations, such as saving the changes to a file,
to internal | 13 * can range from user-facing operations, such as saving the changes to a file,
to internal |
13 * operations, such as tokenizing source code. The information to be logged is g
athered by{@link InstrumentationBuilder instrumentation builder}, created by one
of the static methods on | 14 * operations, such as tokenizing source code. The information to be logged is g
athered by{@link InstrumentationBuilder instrumentation builder}, created by one
of the static methods on |
14 * this class such as {@link #builder(Class)} or {@link #builder(String)}. | 15 * this class such as {@link #builder(Class)} or {@link #builder(String)}. |
15 * <p> | 16 * <p> |
16 * Note, however, that until an instrumentation logger is installed using the me
thod{@link #setLogger(InstrumentationLogger)}, all instrumentation data will be
lost. | 17 * Note, however, that until an instrumentation logger is installed using the me
thod{@link #setLogger(InstrumentationLogger)}, all instrumentation data will be
lost. |
17 * <p> | 18 * <p> |
18 * <b>Example</b> | 19 * <b>Example</b> |
19 * <p> | 20 * <p> |
20 * To collect metrics about how long it took to save a file, you would write som
ething like the | 21 * To collect metrics about how long it took to save a file, you would write som
ething like the |
21 * following: | 22 * following: |
22 * <pre> | 23 * <pre> |
23 * InstrumentationBuilder instrumentation = Instrumentation.builder(this.getClas
s()); | 24 * InstrumentationBuilder instrumentation = Instrumentation.builder(this.getClas
s()); |
24 * // save the file | 25 * // save the file |
25 * instrumentation.metric("chars", fileLength).log(); | 26 * instrumentation.metric("chars", fileLength).log(); |
26 * </pre> | 27 * </pre> |
27 * The {@code Instrumentation.builder} method creates a new {@link Instrumentati
onBuilderinstrumentation builder} and records the time at which it was created.
The{@link InstrumentationBuilder#metric(String,long)} appends the information sp
ecified by the | 28 * The {@code Instrumentation.builder} method creates a new {@link Instrumentati
onBuilderinstrumentation builder} and records the time at which it was created.
The{@link InstrumentationBuilder#metric(String,long)} appends the information sp
ecified by the |
28 * arguments and records the time at which the method is called so that the time
to complete the | 29 * arguments and records the time at which the method is called so that the time
to complete the |
29 * save operation can be calculated. The {@code log} method tells the builder th
at all of the data | 30 * save operation can be calculated. The {@code log} method tells the builder th
at all of the data |
30 * has been collected and that the resulting information should be logged. | 31 * has been collected and that the resulting information should be logged. |
31 * @coverage dart.engine.utilities | 32 * @coverage dart.engine.utilities |
32 */ | 33 */ |
33 class Instrumentation { | 34 class Instrumentation { |
| 35 |
34 /** | 36 /** |
35 * A builder that will silently ignore all data and logging requests. | 37 * A builder that will silently ignore all data and logging requests. |
36 */ | 38 */ |
37 static InstrumentationBuilder _NULL_INSTRUMENTATION_BUILDER = new Instrumentat
ionBuilder_13(); | 39 static InstrumentationBuilder _NULL_INSTRUMENTATION_BUILDER = new Instrumentat
ionBuilder_13(); |
| 40 |
38 /** | 41 /** |
39 * An instrumentation logger that can be used when no other instrumentation lo
gger has been | 42 * An instrumentation logger that can be used when no other instrumentation lo
gger has been |
40 * configured. This logger will silently ignore all data and logging requests. | 43 * configured. This logger will silently ignore all data and logging requests. |
41 */ | 44 */ |
42 static InstrumentationLogger _NULL_LOGGER = new InstrumentationLogger_14(); | 45 static InstrumentationLogger _NULL_LOGGER = new InstrumentationLogger_14(); |
| 46 |
43 /** | 47 /** |
44 * The current instrumentation logger. | 48 * The current instrumentation logger. |
45 */ | 49 */ |
46 static InstrumentationLogger _CURRENT_LOGGER = _NULL_LOGGER; | 50 static InstrumentationLogger _CURRENT_LOGGER = _NULL_LOGGER; |
| 51 |
47 /** | 52 /** |
48 * Create a builder that can collect the data associated with an operation. | 53 * Create a builder that can collect the data associated with an operation. |
49 * @param clazz the class performing the operation (not {@code null}) | 54 * @param clazz the class performing the operation (not {@code null}) |
50 * @return the builder that was created (not {@code null}) | 55 * @return the builder that was created (not {@code null}) |
51 */ | 56 */ |
52 static InstrumentationBuilder builder(Type clazz) => _CURRENT_LOGGER.createBui
lder(clazz.toString()); | 57 static InstrumentationBuilder builder(Type clazz) => _CURRENT_LOGGER.createBui
lder(clazz.toString()); |
| 58 |
53 /** | 59 /** |
54 * Create a builder that can collect the data associated with an operation. | 60 * Create a builder that can collect the data associated with an operation. |
55 * @param name the name used to uniquely identify the operation (not {@code nu
ll}) | 61 * @param name the name used to uniquely identify the operation (not {@code nu
ll}) |
56 * @return the builder that was created (not {@code null}) | 62 * @return the builder that was created (not {@code null}) |
57 */ | 63 */ |
58 static InstrumentationBuilder builder2(String name) => _CURRENT_LOGGER.createB
uilder(name); | 64 static InstrumentationBuilder builder2(String name) => _CURRENT_LOGGER.createB
uilder(name); |
| 65 |
59 /** | 66 /** |
60 * Get the currently active instrumentation logger | 67 * Get the currently active instrumentation logger |
61 */ | 68 */ |
62 static InstrumentationLogger get logger => _CURRENT_LOGGER; | 69 static InstrumentationLogger get logger => _CURRENT_LOGGER; |
| 70 |
63 /** | 71 /** |
64 * Return a builder that will silently ignore all data and logging requests. | 72 * Return a builder that will silently ignore all data and logging requests. |
65 * @return the builder (not {@code null}) | 73 * @return the builder (not {@code null}) |
66 */ | 74 */ |
67 static InstrumentationBuilder get nullBuilder => _NULL_INSTRUMENTATION_BUILDER
; | 75 static InstrumentationBuilder get nullBuilder => _NULL_INSTRUMENTATION_BUILDER
; |
| 76 |
68 /** | 77 /** |
69 * Is this instrumentation system currently configured to drop instrumentation
data provided to | 78 * Is this instrumentation system currently configured to drop instrumentation
data provided to |
70 * it? | 79 * it? |
71 * @return | 80 * @return |
72 */ | 81 */ |
73 static bool isNullLogger() => identical(_CURRENT_LOGGER, _NULL_LOGGER); | 82 static bool isNullLogger() => identical(_CURRENT_LOGGER, _NULL_LOGGER); |
| 83 |
74 /** | 84 /** |
75 * Set the logger that should receive instrumentation information to the given
logger. | 85 * Set the logger that should receive instrumentation information to the given
logger. |
76 * @param logger the logger that should receive instrumentation information | 86 * @param logger the logger that should receive instrumentation information |
77 */ | 87 */ |
78 static void set logger(InstrumentationLogger logger2) { | 88 static void set logger(InstrumentationLogger logger2) { |
79 _CURRENT_LOGGER = logger2 == null ? _NULL_LOGGER : logger2; | 89 _CURRENT_LOGGER = logger2 == null ? _NULL_LOGGER : logger2; |
80 } | 90 } |
81 /** | |
82 * Prevent the creation of instances of this class | |
83 */ | |
84 Instrumentation() { | |
85 } | |
86 } | 91 } |
87 class InstrumentationBuilder_13 implements InstrumentationBuilder { | 92 class InstrumentationBuilder_13 implements InstrumentationBuilder { |
88 InstrumentationBuilder data(String name, bool value) => this; | 93 InstrumentationBuilder data(String name, bool value) => this; |
89 InstrumentationBuilder data2(String name, int value) => this; | 94 InstrumentationBuilder data2(String name, int value) => this; |
90 InstrumentationBuilder data3(String name, String value) => this; | 95 InstrumentationBuilder data3(String name, String value) => this; |
91 InstrumentationBuilder data4(String name, List<String> value) => this; | 96 InstrumentationBuilder data4(String name, List<String> value) => this; |
92 InstrumentationLevel get instrumentationLevel => InstrumentationLevel.OFF; | 97 InstrumentationLevel get instrumentationLevel => InstrumentationLevel.OFF; |
93 void log() { | 98 void log() { |
94 } | 99 } |
95 InstrumentationBuilder metric(String name, bool value) => this; | 100 InstrumentationBuilder metric(String name, bool value) => this; |
96 InstrumentationBuilder metric2(String name, int value) => this; | 101 InstrumentationBuilder metric2(String name, int value) => this; |
97 InstrumentationBuilder metric3(String name, String value) => this; | 102 InstrumentationBuilder metric3(String name, String value) => this; |
98 InstrumentationBuilder metric4(String name, List<String> value) => this; | 103 InstrumentationBuilder metric4(String name, List<String> value) => this; |
99 InstrumentationBuilder record(Exception exception) => this; | 104 InstrumentationBuilder record(Exception exception) => this; |
100 } | 105 } |
101 class InstrumentationLogger_14 implements InstrumentationLogger { | 106 class InstrumentationLogger_14 implements InstrumentationLogger { |
102 InstrumentationBuilder createBuilder(String name) => Instrumentation._NULL_INS
TRUMENTATION_BUILDER; | 107 InstrumentationBuilder createBuilder(String name) => Instrumentation._NULL_INS
TRUMENTATION_BUILDER; |
103 } | 108 } |
| 109 |
104 /** | 110 /** |
105 * The interface {@code InstrumentationBuilder} defines the behavior of objects
used to collect data | 111 * The interface {@code InstrumentationBuilder} defines the behavior of objects
used to collect data |
106 * about an operation that has occurred and record that data through an instrume
ntation logger. | 112 * about an operation that has occurred and record that data through an instrume
ntation logger. |
107 * <p> | 113 * <p> |
108 * For an example of using objects that implement this interface, see {@link Ins
trumentation}. | 114 * For an example of using objects that implement this interface, see {@link Ins
trumentation}. |
109 * @coverage dart.engine.utilities | 115 * @coverage dart.engine.utilities |
110 */ | 116 */ |
111 abstract class InstrumentationBuilder { | 117 abstract class InstrumentationBuilder { |
| 118 |
112 /** | 119 /** |
113 * Append the given data to the data being collected by this builder. The info
rmation is declared | 120 * Append the given data to the data being collected by this builder. The info
rmation is declared |
114 * to potentially contain data that is either user identifiable or contains us
er intellectual | 121 * to potentially contain data that is either user identifiable or contains us
er intellectual |
115 * property (but is not guaranteed to contain either). | 122 * property (but is not guaranteed to contain either). |
116 * @param name the name used to identify the data | 123 * @param name the name used to identify the data |
117 * @param value the value of the data to be collected | 124 * @param value the value of the data to be collected |
118 * @return this builder | 125 * @return this builder |
119 */ | 126 */ |
120 InstrumentationBuilder data(String name, bool value); | 127 InstrumentationBuilder data(String name, bool value); |
| 128 |
121 /** | 129 /** |
122 * Append the given data to the data being collected by this builder. The info
rmation is declared | 130 * Append the given data to the data being collected by this builder. The info
rmation is declared |
123 * to potentially contain data that is either user identifiable or contains us
er intellectual | 131 * to potentially contain data that is either user identifiable or contains us
er intellectual |
124 * property (but is not guaranteed to contain either). | 132 * property (but is not guaranteed to contain either). |
125 * @param name the name used to identify the data | 133 * @param name the name used to identify the data |
126 * @param value the value of the data to be collected | 134 * @param value the value of the data to be collected |
127 * @return this builder | 135 * @return this builder |
128 */ | 136 */ |
129 InstrumentationBuilder data2(String name, int value); | 137 InstrumentationBuilder data2(String name, int value); |
| 138 |
130 /** | 139 /** |
131 * Append the given data to the data being collected by this builder. The info
rmation is declared | 140 * Append the given data to the data being collected by this builder. The info
rmation is declared |
132 * to potentially contain data that is either user identifiable or contains us
er intellectual | 141 * to potentially contain data that is either user identifiable or contains us
er intellectual |
133 * property (but is not guaranteed to contain either). | 142 * property (but is not guaranteed to contain either). |
134 * @param name the name used to identify the data | 143 * @param name the name used to identify the data |
135 * @param value the value of the data to be collected | 144 * @param value the value of the data to be collected |
136 * @return this builder | 145 * @return this builder |
137 */ | 146 */ |
138 InstrumentationBuilder data3(String name, String value); | 147 InstrumentationBuilder data3(String name, String value); |
| 148 |
139 /** | 149 /** |
140 * Append the given data to the data being collected by this builder. The info
rmation is declared | 150 * Append the given data to the data being collected by this builder. The info
rmation is declared |
141 * to potentially contain data that is either user identifiable or contains us
er intellectual | 151 * to potentially contain data that is either user identifiable or contains us
er intellectual |
142 * property (but is not guaranteed to contain either). | 152 * property (but is not guaranteed to contain either). |
143 * @param name the name used to identify the data | 153 * @param name the name used to identify the data |
144 * @param value the value of the data to be collected | 154 * @param value the value of the data to be collected |
145 * @return this builder | 155 * @return this builder |
146 */ | 156 */ |
147 InstrumentationBuilder data4(String name, List<String> value); | 157 InstrumentationBuilder data4(String name, List<String> value); |
| 158 |
148 /** | 159 /** |
149 * Answer the {@link InstrumentationLevel} of this {@code InstrumentationBuild
er}. | 160 * Answer the {@link InstrumentationLevel} of this {@code InstrumentationBuild
er}. |
150 * @return one of {@link InstrumentationLevel#EVERYTHING}, {@link Instrumentat
ionLevel#METRICS},{@link InstrumentationLevel#OFF} | 161 * @return one of {@link InstrumentationLevel#EVERYTHING}, {@link Instrumentat
ionLevel#METRICS},{@link InstrumentationLevel#OFF} |
151 */ | 162 */ |
152 InstrumentationLevel get instrumentationLevel; | 163 InstrumentationLevel get instrumentationLevel; |
| 164 |
153 /** | 165 /** |
154 * Log the data that has been collected. The instrumentation builder should no
t be used after this | 166 * Log the data that has been collected. The instrumentation builder should no
t be used after this |
155 * method is invoked. The behavior of any method defined on this interface tha
t is used after this | 167 * method is invoked. The behavior of any method defined on this interface tha
t is used after this |
156 * method is invoked is undefined. | 168 * method is invoked is undefined. |
157 */ | 169 */ |
158 void log(); | 170 void log(); |
| 171 |
159 /** | 172 /** |
160 * Append the given metric to the data being collected by this builder. The in
formation is | 173 * Append the given metric to the data being collected by this builder. The in
formation is |
161 * declared to contain only metrics data (data that is not user identifiable a
nd does not contain | 174 * declared to contain only metrics data (data that is not user identifiable a
nd does not contain |
162 * user intellectual property). | 175 * user intellectual property). |
163 * @param name the name used to identify the data | 176 * @param name the name used to identify the data |
164 * @param value the value of the data to be collected | 177 * @param value the value of the data to be collected |
165 * @return this builder | 178 * @return this builder |
166 */ | 179 */ |
167 InstrumentationBuilder metric(String name, bool value); | 180 InstrumentationBuilder metric(String name, bool value); |
| 181 |
168 /** | 182 /** |
169 * Append the given metric to the data being collected by this builder. The in
formation is | 183 * Append the given metric to the data being collected by this builder. The in
formation is |
170 * declared to contain only metrics data (data that is not user identifiable a
nd does not contain | 184 * declared to contain only metrics data (data that is not user identifiable a
nd does not contain |
171 * user intellectual property). | 185 * user intellectual property). |
172 * @param name the name used to identify the data | 186 * @param name the name used to identify the data |
173 * @param value the value of the data to be collected | 187 * @param value the value of the data to be collected |
174 * @return this builder | 188 * @return this builder |
175 */ | 189 */ |
176 InstrumentationBuilder metric2(String name, int value); | 190 InstrumentationBuilder metric2(String name, int value); |
| 191 |
177 /** | 192 /** |
178 * Append the given metric to the data being collected by this builder. The in
formation is | 193 * Append the given metric to the data being collected by this builder. The in
formation is |
179 * declared to contain only metrics data (data that is not user identifiable a
nd does not contain | 194 * declared to contain only metrics data (data that is not user identifiable a
nd does not contain |
180 * user intellectual property). | 195 * user intellectual property). |
181 * @param name the name used to identify the data | 196 * @param name the name used to identify the data |
182 * @param value the value of the data to be collected | 197 * @param value the value of the data to be collected |
183 * @return this builder | 198 * @return this builder |
184 */ | 199 */ |
185 InstrumentationBuilder metric3(String name, String value); | 200 InstrumentationBuilder metric3(String name, String value); |
| 201 |
186 /** | 202 /** |
187 * Append the given metric to the data being collected by this builder. The in
formation is | 203 * Append the given metric to the data being collected by this builder. The in
formation is |
188 * declared to contain only metrics data (data that is not user identifiable a
nd does not contain | 204 * declared to contain only metrics data (data that is not user identifiable a
nd does not contain |
189 * user intellectual property). | 205 * user intellectual property). |
190 * @param name the name used to identify the data | 206 * @param name the name used to identify the data |
191 * @param value the value of the data to be collected | 207 * @param value the value of the data to be collected |
192 * @return this builder | 208 * @return this builder |
193 */ | 209 */ |
194 InstrumentationBuilder metric4(String name, List<String> value); | 210 InstrumentationBuilder metric4(String name, List<String> value); |
| 211 |
195 /** | 212 /** |
196 * Append the given exception to the information being collected by this build
er. The exception's | 213 * Append the given exception to the information being collected by this build
er. The exception's |
197 * class name is captured using {@link #metric(String,String)}. Other aspects
of the exception | 214 * class name is captured using {@link #metric(String,String)}. Other aspects
of the exception |
198 * may contain either user identifiable or contains user intellectual property
(but is not | 215 * may contain either user identifiable or contains user intellectual property
(but is not |
199 * guaranteed to contain either) and thus are captured using the various data
methods such as{@link #data(String,String)}. | 216 * guaranteed to contain either) and thus are captured using the various data
methods such as{@link #data(String,String)}. |
200 * @param exception the exception (may be {@code null}) | 217 * @param exception the exception (may be {@code null}) |
201 */ | 218 */ |
202 InstrumentationBuilder record(Exception exception); | 219 InstrumentationBuilder record(Exception exception); |
203 } | 220 } |
| 221 |
204 /** | 222 /** |
205 * The instrumentation recording level representing (1) recording {@link #EVERYT
HING} recording of | 223 * The instrumentation recording level representing (1) recording {@link #EVERYT
HING} recording of |
206 * all instrumentation data, (2) recording only {@link #METRICS} information, or
(3) recording | 224 * all instrumentation data, (2) recording only {@link #METRICS} information, or
(3) recording |
207 * turned {@link #OFF} in which case nothing is recorded. | 225 * turned {@link #OFF} in which case nothing is recorded. |
208 * @coverage dart.engine.utilities | 226 * @coverage dart.engine.utilities |
209 */ | 227 */ |
210 class InstrumentationLevel implements Comparable<InstrumentationLevel> { | 228 class InstrumentationLevel implements Comparable<InstrumentationLevel> { |
| 229 |
211 /** | 230 /** |
212 * Recording all instrumented information | 231 * Recording all instrumented information |
213 */ | 232 */ |
214 static final InstrumentationLevel EVERYTHING = new InstrumentationLevel('EVERY
THING', 0); | 233 static final InstrumentationLevel EVERYTHING = new InstrumentationLevel('EVERY
THING', 0); |
| 234 |
215 /** | 235 /** |
216 * Recording only metrics | 236 * Recording only metrics |
217 */ | 237 */ |
218 static final InstrumentationLevel METRICS = new InstrumentationLevel('METRICS'
, 1); | 238 static final InstrumentationLevel METRICS = new InstrumentationLevel('METRICS'
, 1); |
| 239 |
219 /** | 240 /** |
220 * Nothing recorded | 241 * Nothing recorded |
221 */ | 242 */ |
222 static final InstrumentationLevel OFF = new InstrumentationLevel('OFF', 2); | 243 static final InstrumentationLevel OFF = new InstrumentationLevel('OFF', 2); |
223 static final List<InstrumentationLevel> values = [EVERYTHING, METRICS, OFF]; | 244 static final List<InstrumentationLevel> values = [EVERYTHING, METRICS, OFF]; |
224 final String __name; | 245 |
225 final int __ordinal; | 246 /// The name of this enum constant, as declared in the enum declaration. |
226 int get ordinal => __ordinal; | 247 final String name; |
| 248 |
| 249 /// The position in the enum declaration. |
| 250 final int ordinal; |
227 static InstrumentationLevel fromString(String str) { | 251 static InstrumentationLevel fromString(String str) { |
228 if (str == "EVERYTHING") { | 252 if (str == "EVERYTHING") { |
229 return InstrumentationLevel.EVERYTHING; | 253 return InstrumentationLevel.EVERYTHING; |
230 } | 254 } |
231 if (str == "METRICS") { | 255 if (str == "METRICS") { |
232 return InstrumentationLevel.METRICS; | 256 return InstrumentationLevel.METRICS; |
233 } | 257 } |
234 if (str == "OFF") { | 258 if (str == "OFF") { |
235 return InstrumentationLevel.OFF; | 259 return InstrumentationLevel.OFF; |
236 } | 260 } |
237 throw new IllegalArgumentException("Unrecognised InstrumentationLevel"); | 261 throw new IllegalArgumentException("Unrecognised InstrumentationLevel"); |
238 } | 262 } |
239 InstrumentationLevel(this.__name, this.__ordinal) { | 263 InstrumentationLevel(this.name, this.ordinal) { |
240 } | 264 } |
241 int compareTo(InstrumentationLevel other) => __ordinal - other.__ordinal; | 265 int compareTo(InstrumentationLevel other) => ordinal - other.ordinal; |
242 String toString() => __name; | 266 String toString() => name; |
243 } | 267 } |
| 268 |
244 /** | 269 /** |
245 * The interface {@code InstrumentationLogger} defines the behavior of objects t
hat are used to log | 270 * The interface {@code InstrumentationLogger} defines the behavior of objects t
hat are used to log |
246 * instrumentation data. | 271 * instrumentation data. |
247 * <p> | 272 * <p> |
248 * For an example of using objects that implement this interface, see {@link Ins
trumentation}. | 273 * For an example of using objects that implement this interface, see {@link Ins
trumentation}. |
249 * @coverage dart.engine.utilities | 274 * @coverage dart.engine.utilities |
250 */ | 275 */ |
251 abstract class InstrumentationLogger { | 276 abstract class InstrumentationLogger { |
| 277 |
252 /** | 278 /** |
253 * Create a builder that can collect the data associated with an operation ide
ntified by the given | 279 * Create a builder that can collect the data associated with an operation ide
ntified by the given |
254 * name. | 280 * name. |
255 * @param name the name used to uniquely identify the operation | 281 * @param name the name used to uniquely identify the operation |
256 * @return the builder that was created | 282 * @return the builder that was created |
257 */ | 283 */ |
258 InstrumentationBuilder createBuilder(String name); | 284 InstrumentationBuilder createBuilder(String name); |
259 } | 285 } |
OLD | NEW |