Debian Codegraph @

closure-library/closure/goog/debug/errorreporter.js

raw
1 // Copyright 2009 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Definition of the ErrorReporter class, which creates an error
17 * handler that reports any errors raised to a URL.
18 *
19 */
20
21 goog.provide('goog.debug.ErrorReporter');
22 goog.provide('goog.debug.ErrorReporter.ExceptionEvent');
23
24 goog.require('goog.asserts');
25 goog.require('goog.debug');
26 goog.require('goog.debug.Error');
27 goog.require('goog.debug.ErrorHandler');
28 goog.require('goog.debug.entryPointRegistry');
29 goog.require('goog.debug.errorcontext');
30 goog.require('goog.events');
31 goog.require('goog.events.Event');
32 goog.require('goog.events.EventTarget');
33 goog.require('goog.log');
34 goog.require('goog.net.XhrIo');
35 goog.require('goog.object');
36 goog.require('goog.string');
37 goog.require('goog.uri.utils');
38 goog.require('goog.userAgent');
39
40
41
42 /**
43 * Constructs an error reporter. Internal Use Only. To install an error
44 * reporter see the {@see #install} method below.
45 *
46 * @param {string} handlerUrl The URL to which all errors will be reported.
47 * @param {function(!Error, !Object<string, string>)=}
48 * opt_contextProvider When a report is to be sent to the server,
49 * this method will be called, and given an opportunity to modify the
50 * context object before submission to the server.
51 * @param {boolean=} opt_noAutoProtect Whether to automatically add handlers for
52 * onerror and to protect entry points. If apps have other error reporting
53 * facilities, it may make sense for them to set these up themselves and use
54 * the ErrorReporter just for transmission of reports.
55 * @constructor
56 * @extends {goog.events.EventTarget}
57 */
58 goog.debug.ErrorReporter = function(
59 handlerUrl, opt_contextProvider, opt_noAutoProtect) {
60 goog.debug.ErrorReporter.base(this, 'constructor');
61
62 /**
63 * Context provider, if one was provided.
64 * @type {?function(!Error, !Object<string, string>)}
65 * @private
66 */
67 this.contextProvider_ = opt_contextProvider || null;
68
69 /**
70 * The string prefix of any optional context parameters logged with the error.
71 * @private {string}
72 */
73 this.contextPrefix_ = 'context.';
74
75 /**
76 * The number of bytes after which the ErrorReporter truncates the POST body.
77 * If null, the ErrorReporter won't truncate the body.
78 * @private {?number}
79 */
80 this.truncationLimit_ = null;
81
82 /**
83 * Additional arguments to append to URL before sending XHR.
84 * @private {!Object<string,string>}
85 */
86 this.additionalArguments_ = {};
87
88 /**
89 * XHR sender.
90 * @type {function(string, string, string, (Object|goog.structs.Map)=)}
91 * @private
92 */
93 this.xhrSender_ = goog.debug.ErrorReporter.defaultXhrSender;
94
95 /**
96 * The URL at which all errors caught by this handler will be logged.
97 *
98 * @type {string}
99 * @private
100 */
101 this.handlerUrl_ = handlerUrl;
102
103 if (goog.debug.ErrorReporter.ALLOW_AUTO_PROTECT) {
104 if (!opt_noAutoProtect) {
105 /**
106 * The internal error handler used to catch all errors.
107 *
108 * @private {goog.debug.ErrorHandler}
109 */
110 this.errorHandler_ = null;
111
112 this.setup_();
113 }
114 } else if (!opt_noAutoProtect) {
115 goog.asserts.fail(
116 'opt_noAutoProtect cannot be false while ' +
117 'goog.debug.ErrorReporter.ALLOW_AUTO_PROTECT is false. Setting ' +
118 'ALLOW_AUTO_PROTECT to false removes the necessary auto-protect code ' +
119 'in compiled/optimized mode.');
120 }
121 };
122 goog.inherits(goog.debug.ErrorReporter, goog.events.EventTarget);
123
124
125 /**
126 * @define {boolean} If true, the code that provides additional entry point
127 * protection and setup is exposed in this file. Set to false to avoid
128 * bringing in a lot of code from ErrorHandler and entryPointRegistry in
129 * compiled mode.
130 */
131 goog.define('goog.debug.ErrorReporter.ALLOW_AUTO_PROTECT', true);
132
133
134
135 /**
136 * Event broadcast when an exception is logged.
137 * @param {Error} error The exception that was was reported.
138 * @param {!Object<string, string>} context The context values sent to the
139 * server alongside this error.
140 * @constructor
141 * @extends {goog.events.Event}
142 * @final
143 */
144 goog.debug.ErrorReporter.ExceptionEvent = function(error, context) {
145 goog.events.Event.call(this, goog.debug.ErrorReporter.ExceptionEvent.TYPE);
146
147 /**
148 * The error that was reported.
149 * @type {Error}
150 */
151 this.error = error;
152
153 /**
154 * Context values sent to the server alongside this report.
155 * @type {!Object<string, string>}
156 */
157 this.context = context;
158 };
159 goog.inherits(goog.debug.ErrorReporter.ExceptionEvent, goog.events.Event);
160
161
162 /**
163 * Event type for notifying of a logged exception.
164 * @type {string}
165 */
166 goog.debug.ErrorReporter.ExceptionEvent.TYPE =
167 goog.events.getUniqueId('exception');
168
169
170 /**
171 * Extra headers for the error-reporting XHR.
172 * @type {Object|goog.structs.Map|undefined}
173 * @private
174 */
175 goog.debug.ErrorReporter.prototype.extraHeaders_;
176
177
178 /**
179 * Logging object.
180 *
181 * @type {goog.log.Logger}
182 * @private
183 */
184 goog.debug.ErrorReporter.logger_ =
185 goog.log.getLogger('goog.debug.ErrorReporter');
186
187
188 /**
189 * Installs an error reporter to catch all JavaScript errors raised.
190 *
191 * @param {string} loggingUrl The URL to which the errors caught will be
192 * reported.
193 * @param {function(!Error, !Object<string, string>)=}
194 * opt_contextProvider When a report is to be sent to the server,
195 * this method will be called, and given an opportunity to modify the
196 * context object before submission to the server.
197 * @param {boolean=} opt_noAutoProtect Whether to automatically add handlers for
198 * onerror and to protect entry points. If apps have other error reporting
199 * facilities, it may make sense for them to set these up themselves and use
200 * the ErrorReporter just for transmission of reports.
201 * @return {!goog.debug.ErrorReporter} The error reporter.
202 */
203 goog.debug.ErrorReporter.install = function(
204 loggingUrl, opt_contextProvider, opt_noAutoProtect) {
205 var instance = new goog.debug.ErrorReporter(
206 loggingUrl, opt_contextProvider, opt_noAutoProtect);
207 return instance;
208 };
209
210
211 /**
212 * Default implementation of XHR sender interface.
213 *
214 * @param {string} uri URI to make request to.
215 * @param {string} method Send method.
216 * @param {string} content Post data.
217 * @param {Object|goog.structs.Map=} opt_headers Map of headers to add to the
218 * request.
219 */
220 goog.debug.ErrorReporter.defaultXhrSender = function(
221 uri, method, content, opt_headers) {
222 goog.net.XhrIo.send(uri, null, method, content, opt_headers);
223 };
224
225
226 /**
227 * Installs exception protection for an entry point function in addition
228 * to those that are protected by default.
229 * Has no effect in IE because window.onerror is used for reporting
230 * exceptions in that case.
231 *
232 * @this {goog.debug.ErrorReporter}
233 * @param {Function} fn An entry point function to be protected.
234 * @return {Function} A protected wrapper function that calls the entry point
235 * function or null if the entry point could not be protected.
236 */
237 goog.debug.ErrorReporter.prototype.protectAdditionalEntryPoint =
238 goog.debug.ErrorReporter.ALLOW_AUTO_PROTECT ? function(fn) {
239 if (this.errorHandler_) {
240 return this.errorHandler_.protectEntryPoint(fn);
241 }
242 return null;
243 } : function(fn) {
244 goog.asserts.fail(
245 'Cannot call protectAdditionalEntryPoint while ALLOW_AUTO_PROTECT ' +
246 'is false. If ALLOW_AUTO_PROTECT is false, the necessary ' +
247 'auto-protect code in compiled/optimized mode is removed.');
248 return null;
249 };
250
251
252 if (goog.debug.ErrorReporter.ALLOW_AUTO_PROTECT) {
253 /**
254 * Sets up the error reporter.
255 *
256 * @private
257 */
258 goog.debug.ErrorReporter.prototype.setup_ = function() {
259 if (goog.userAgent.IE && !goog.userAgent.isVersionOrHigher('10')) {
260 // Use "onerror" because caught exceptions in IE don't provide line
261 // number.
262 goog.debug.catchErrors(
263 goog.bind(this.handleException, this), false, null);
264 } else {
265 // "onerror" doesn't work with FF2 or Chrome
266 this.errorHandler_ =
267 new goog.debug.ErrorHandler(goog.bind(this.handleException, this));
268
269 this.errorHandler_.protectWindowSetTimeout();
270 this.errorHandler_.protectWindowSetInterval();
271 this.errorHandler_.protectWindowRequestAnimationFrame();
272 goog.debug.entryPointRegistry.monitorAll(this.errorHandler_);
273 }
274 };
275 }
276
277
278 /**
279 * Add headers to the logging url.
280 * @param {Object|goog.structs.Map} loggingHeaders Extra headers to send
281 * to the logging URL.
282 */
283 goog.debug.ErrorReporter.prototype.setLoggingHeaders = function(
284 loggingHeaders) {
285 this.extraHeaders_ = loggingHeaders;
286 };
287
288
289 /**
290 * Set the function used to send error reports to the server.
291 * @param {function(string, string, string, (Object|goog.structs.Map)=)}
292 * xhrSender If provided, this will be used to send a report to the
293 * server instead of the default method. The function will be given the URI,
294 * HTTP method request content, and (optionally) request headers to be
295 * added.
296 */
297 goog.debug.ErrorReporter.prototype.setXhrSender = function(xhrSender) {
298 this.xhrSender_ = xhrSender;
299 };
300
301
302 /**
303 * Handler for caught exceptions. Sends report to the LoggingServlet and
304 * notifies any listeners.
305 *
306 * @param {Object} e The exception.
307 * @param {!Object<string, string>=} opt_context Context values to optionally
308 * include in the error report.
309 */
310 goog.debug.ErrorReporter.prototype.handleException = function(e, opt_context) {
311 // goog.debug.catchErrors passes the actual error object (in some browsers) in
312 // the error property. If we have that, use that instead of the incomplete set
313 // of random properties passed to window.onerror.
314 e = e.error || e;
315 // Construct the context, possibly from the one provided in the argument, and
316 // pass it to the context provider if there is one.
317 var context = opt_context ? goog.object.clone(opt_context) : {};
318 if (e instanceof Error) {
319 goog.object.extend(
320 context,
321 goog.debug.errorcontext.getErrorContext(/** @type {!Error} */ (e)));
322 }
323
324 var error = /** @type {!Error} */ (goog.debug.normalizeErrorObject(e));
325
326 if (this.contextProvider_) {
327 try {
328 this.contextProvider_(error, context);
329 } catch (err) {
330 goog.log.error(
331 goog.debug.ErrorReporter.logger_,
332 'Context provider threw an exception: ' + err.message);
333 }
334 }
335 // Truncate message to a reasonable length, since it will be sent in the URL.
336 // The entire URL length historically needed to be 2,083 or less, so leave
337 // some room for the rest of the URL.
338 var message = error.message.substring(0, 1900);
339 if (!(e instanceof goog.debug.Error) || e.reportErrorToServer) {
340 this.sendErrorReport(
341 message, error.fileName, error.lineNumber, error.stack, context);
342 }
343
344 try {
345 this.dispatchEvent(
346 new goog.debug.ErrorReporter.ExceptionEvent(error, context));
347 } catch (ex) {
348 // Swallow exception to avoid infinite recursion.
349 }
350 };
351
352
353 /**
354 * Sends an error report to the logging URL. This will not consult the context
355 * provider, the report will be sent exactly as specified.
356 *
357 * @param {string} message Error description.
358 * @param {string} fileName URL of the JavaScript file with the error.
359 * @param {number} line Line number of the error.
360 * @param {string=} opt_trace Call stack trace of the error.
361 * @param {!Object<string, string>=} opt_context Context information to include
362 * in the request.
363 */
364 goog.debug.ErrorReporter.prototype.sendErrorReport = function(
365 message, fileName, line, opt_trace, opt_context) {
366 try {
367 // Create the logging URL.
368 var requestUrl = goog.uri.utils.appendParams(
369 this.handlerUrl_, 'script', fileName, 'error', message, 'line', line);
370
371 if (!goog.object.isEmpty(this.additionalArguments_)) {
372 requestUrl = goog.uri.utils.appendParamsFromMap(
373 requestUrl, this.additionalArguments_);
374 }
375
376 var queryMap = {};
377 queryMap['trace'] = opt_trace;
378
379 // Copy context into query data map
380 if (opt_context) {
381 for (var entry in opt_context) {
382 queryMap[this.contextPrefix_ + entry] = opt_context[entry];
383 }
384 }
385
386 // Copy query data map into request.
387 var queryData = goog.uri.utils.buildQueryDataFromMap(queryMap);
388
389 // Truncate if truncationLimit set.
390 if (goog.isNumber(this.truncationLimit_)) {
391 queryData = queryData.substring(0, this.truncationLimit_);
392 }
393
394 // Send the request with the contents of the error.
395 this.xhrSender_(requestUrl, 'POST', queryData, this.extraHeaders_);
396 } catch (e) {
397 var logMessage = goog.string.buildString(
398 'Error occurred in sending an error report.\n\n', 'script:', fileName,
399 '\n', 'line:', line, '\n', 'error:', message, '\n', 'trace:',
400 opt_trace);
401 goog.log.info(goog.debug.ErrorReporter.logger_, logMessage);
402 }
403 };
404
405
406 /**
407 * @param {string} prefix The prefix to appear prepended to all context
408 * variables in the error report body.
409 */
410 goog.debug.ErrorReporter.prototype.setContextPrefix = function(prefix) {
411 this.contextPrefix_ = prefix;
412 };
413
414
415 /**
416 * @param {?number} limit Size in bytes to begin truncating POST body. Set to
417 * null to prevent truncation. The limit must be >= 0.
418 */
419 goog.debug.ErrorReporter.prototype.setTruncationLimit = function(limit) {
420 goog.asserts.assert(
421 !goog.isNumber(limit) || limit >= 0,
422 'Body limit must be valid number >= 0 or null');
423 this.truncationLimit_ = limit;
424 };
425
426
427 /**
428 * @param {!Object<string,string>} urlArgs Set of key-value pairs to append
429 * to handlerUrl_ before sending XHR.
430 */
431 goog.debug.ErrorReporter.prototype.setAdditionalArguments = function(urlArgs) {
432 this.additionalArguments_ = urlArgs;
433 };
434
435
436 /** @override */
437 goog.debug.ErrorReporter.prototype.disposeInternal = function() {
438 if (goog.debug.ErrorReporter.ALLOW_AUTO_PROTECT) {
439 goog.dispose(this.errorHandler_);
440 }
441 goog.debug.ErrorReporter.base(this, 'disposeInternal');
442 };