| 1 |
// Copyright 2006 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 Logger class. Please minimize dependencies |
| 17 |
* this file has on other closure classes as any dependency it takes won't be |
| 18 |
* able to use the logging infrastructure. |
| 19 |
* |
| 20 |
* @see ../demos/debug.html |
| 21 |
*/ |
| 22 |
|
| 23 |
goog.provide('goog.debug.LogManager'); |
| 24 |
goog.provide('goog.debug.Loggable'); |
| 25 |
goog.provide('goog.debug.Logger'); |
| 26 |
goog.provide('goog.debug.Logger.Level'); |
| 27 |
|
| 28 |
goog.require('goog.array'); |
| 29 |
goog.require('goog.asserts'); |
| 30 |
goog.require('goog.debug'); |
| 31 |
goog.require('goog.debug.LogBuffer'); |
| 32 |
goog.require('goog.debug.LogRecord'); |
| 33 |
|
| 34 |
|
| 35 |
/** |
| 36 |
* A message value that can be handled by a Logger. |
| 37 |
* |
| 38 |
* Functions are treated like callbacks, but are only called when the event's |
| 39 |
* log level is enabled. This is useful for logging messages that are expensive |
| 40 |
* to construct. |
| 41 |
* |
| 42 |
* @typedef {string|function(): string} |
| 43 |
*/ |
| 44 |
goog.debug.Loggable; |
| 45 |
|
| 46 |
|
| 47 |
|
| 48 |
/** |
| 49 |
* The Logger is an object used for logging debug messages. Loggers are |
| 50 |
* normally named, using a hierarchical dot-separated namespace. Logger names |
| 51 |
* can be arbitrary strings, but they should normally be based on the package |
| 52 |
* name or class name of the logged component, such as goog.net.BrowserChannel. |
| 53 |
* |
| 54 |
* The Logger object is loosely based on the java class |
| 55 |
* java.util.logging.Logger. It supports different levels of filtering for |
| 56 |
* different loggers. |
| 57 |
* |
| 58 |
* The logger object should never be instantiated by application code. It |
| 59 |
* should always use the goog.debug.Logger.getLogger function. |
| 60 |
* |
| 61 |
* @constructor |
| 62 |
* @param {string} name The name of the Logger. |
| 63 |
* @final |
| 64 |
*/ |
| 65 |
goog.debug.Logger = function(name) { |
| 66 |
/** |
| 67 |
* Name of the Logger. Generally a dot-separated namespace |
| 68 |
* @private {string} |
| 69 |
*/ |
| 70 |
this.name_ = name; |
| 71 |
|
| 72 |
/** |
| 73 |
* Parent Logger. |
| 74 |
* @private {goog.debug.Logger} |
| 75 |
*/ |
| 76 |
this.parent_ = null; |
| 77 |
|
| 78 |
/** |
| 79 |
* Level that this logger only filters above. Null indicates it should |
| 80 |
* inherit from the parent. |
| 81 |
* @private {goog.debug.Logger.Level} |
| 82 |
*/ |
| 83 |
this.level_ = null; |
| 84 |
|
| 85 |
/** |
| 86 |
* Map of children loggers. The keys are the leaf names of the children and |
| 87 |
* the values are the child loggers. |
| 88 |
* @private {Object} |
| 89 |
*/ |
| 90 |
this.children_ = null; |
| 91 |
|
| 92 |
/** |
| 93 |
* Handlers that are listening to this logger. |
| 94 |
* @private {Array<Function>} |
| 95 |
*/ |
| 96 |
this.handlers_ = null; |
| 97 |
}; |
| 98 |
|
| 99 |
|
| 100 |
/** @const */ |
| 101 |
goog.debug.Logger.ROOT_LOGGER_NAME = ''; |
| 102 |
|
| 103 |
|
| 104 |
/** |
| 105 |
* @define {boolean} Toggles whether loggers other than the root logger can have |
| 106 |
* log handlers attached to them and whether they can have their log level |
| 107 |
* set. Logging is a bit faster when this is set to false. |
| 108 |
*/ |
| 109 |
goog.define('goog.debug.Logger.ENABLE_HIERARCHY', true); |
| 110 |
|
| 111 |
|
| 112 |
/** |
| 113 |
* @define {boolean} Toggles whether active log statements are also recorded |
| 114 |
* to the profiler. |
| 115 |
*/ |
| 116 |
goog.define('goog.debug.Logger.ENABLE_PROFILER_LOGGING', false); |
| 117 |
|
| 118 |
|
| 119 |
if (!goog.debug.Logger.ENABLE_HIERARCHY) { |
| 120 |
/** |
| 121 |
* @type {!Array<Function>} |
| 122 |
* @private |
| 123 |
*/ |
| 124 |
goog.debug.Logger.rootHandlers_ = []; |
| 125 |
|
| 126 |
|
| 127 |
/** |
| 128 |
* @type {goog.debug.Logger.Level} |
| 129 |
* @private |
| 130 |
*/ |
| 131 |
goog.debug.Logger.rootLevel_; |
| 132 |
} |
| 133 |
|
| 134 |
|
| 135 |
|
| 136 |
/** |
| 137 |
* The Level class defines a set of standard logging levels that |
| 138 |
* can be used to control logging output. The logging Level objects |
| 139 |
* are ordered and are specified by ordered integers. Enabling logging |
| 140 |
* at a given level also enables logging at all higher levels. |
| 141 |
* <p> |
| 142 |
* Clients should normally use the predefined Level constants such |
| 143 |
* as Level.SEVERE. |
| 144 |
* <p> |
| 145 |
* The levels in descending order are: |
| 146 |
* <ul> |
| 147 |
* <li>SEVERE (highest value) |
| 148 |
* <li>WARNING |
| 149 |
* <li>INFO |
| 150 |
* <li>CONFIG |
| 151 |
* <li>FINE |
| 152 |
* <li>FINER |
| 153 |
* <li>FINEST (lowest value) |
| 154 |
* </ul> |
| 155 |
* In addition there is a level OFF that can be used to turn |
| 156 |
* off logging, and a level ALL that can be used to enable |
| 157 |
* logging of all messages. |
| 158 |
* |
| 159 |
* @param {string} name The name of the level. |
| 160 |
* @param {number} value The numeric value of the level. |
| 161 |
* @constructor |
| 162 |
* @final |
| 163 |
*/ |
| 164 |
goog.debug.Logger.Level = function(name, value) { |
| 165 |
/** |
| 166 |
* The name of the level |
| 167 |
* @type {string} |
| 168 |
*/ |
| 169 |
this.name = name; |
| 170 |
|
| 171 |
/** |
| 172 |
* The numeric value of the level |
| 173 |
* @type {number} |
| 174 |
*/ |
| 175 |
this.value = value; |
| 176 |
}; |
| 177 |
|
| 178 |
|
| 179 |
/** |
| 180 |
* @return {string} String representation of the logger level. |
| 181 |
* @override |
| 182 |
*/ |
| 183 |
goog.debug.Logger.Level.prototype.toString = function() { |
| 184 |
return this.name; |
| 185 |
}; |
| 186 |
|
| 187 |
|
| 188 |
/** |
| 189 |
* OFF is a special level that can be used to turn off logging. |
| 190 |
* This level is initialized to <CODE>Infinity</CODE>. |
| 191 |
* @type {!goog.debug.Logger.Level} |
| 192 |
*/ |
| 193 |
goog.debug.Logger.Level.OFF = new goog.debug.Logger.Level('OFF', Infinity); |
| 194 |
|
| 195 |
|
| 196 |
/** |
| 197 |
* SHOUT is a message level for extra debugging loudness. |
| 198 |
* This level is initialized to <CODE>1200</CODE>. |
| 199 |
* @type {!goog.debug.Logger.Level} |
| 200 |
*/ |
| 201 |
goog.debug.Logger.Level.SHOUT = new goog.debug.Logger.Level('SHOUT', 1200); |
| 202 |
|
| 203 |
|
| 204 |
/** |
| 205 |
* SEVERE is a message level indicating a serious failure. |
| 206 |
* This level is initialized to <CODE>1000</CODE>. |
| 207 |
* @type {!goog.debug.Logger.Level} |
| 208 |
*/ |
| 209 |
goog.debug.Logger.Level.SEVERE = new goog.debug.Logger.Level('SEVERE', 1000); |
| 210 |
|
| 211 |
|
| 212 |
/** |
| 213 |
* WARNING is a message level indicating a potential problem. |
| 214 |
* This level is initialized to <CODE>900</CODE>. |
| 215 |
* @type {!goog.debug.Logger.Level} |
| 216 |
*/ |
| 217 |
goog.debug.Logger.Level.WARNING = new goog.debug.Logger.Level('WARNING', 900); |
| 218 |
|
| 219 |
|
| 220 |
/** |
| 221 |
* INFO is a message level for informational messages. |
| 222 |
* This level is initialized to <CODE>800</CODE>. |
| 223 |
* @type {!goog.debug.Logger.Level} |
| 224 |
*/ |
| 225 |
goog.debug.Logger.Level.INFO = new goog.debug.Logger.Level('INFO', 800); |
| 226 |
|
| 227 |
|
| 228 |
/** |
| 229 |
* CONFIG is a message level for static configuration messages. |
| 230 |
* This level is initialized to <CODE>700</CODE>. |
| 231 |
* @type {!goog.debug.Logger.Level} |
| 232 |
*/ |
| 233 |
goog.debug.Logger.Level.CONFIG = new goog.debug.Logger.Level('CONFIG', 700); |
| 234 |
|
| 235 |
|
| 236 |
/** |
| 237 |
* FINE is a message level providing tracing information. |
| 238 |
* This level is initialized to <CODE>500</CODE>. |
| 239 |
* @type {!goog.debug.Logger.Level} |
| 240 |
*/ |
| 241 |
goog.debug.Logger.Level.FINE = new goog.debug.Logger.Level('FINE', 500); |
| 242 |
|
| 243 |
|
| 244 |
/** |
| 245 |
* FINER indicates a fairly detailed tracing message. |
| 246 |
* This level is initialized to <CODE>400</CODE>. |
| 247 |
* @type {!goog.debug.Logger.Level} |
| 248 |
*/ |
| 249 |
goog.debug.Logger.Level.FINER = new goog.debug.Logger.Level('FINER', 400); |
| 250 |
|
| 251 |
/** |
| 252 |
* FINEST indicates a highly detailed tracing message. |
| 253 |
* This level is initialized to <CODE>300</CODE>. |
| 254 |
* @type {!goog.debug.Logger.Level} |
| 255 |
*/ |
| 256 |
|
| 257 |
goog.debug.Logger.Level.FINEST = new goog.debug.Logger.Level('FINEST', 300); |
| 258 |
|
| 259 |
|
| 260 |
/** |
| 261 |
* ALL indicates that all messages should be logged. |
| 262 |
* This level is initialized to <CODE>0</CODE>. |
| 263 |
* @type {!goog.debug.Logger.Level} |
| 264 |
*/ |
| 265 |
goog.debug.Logger.Level.ALL = new goog.debug.Logger.Level('ALL', 0); |
| 266 |
|
| 267 |
|
| 268 |
/** |
| 269 |
* The predefined levels. |
| 270 |
* @type {!Array<!goog.debug.Logger.Level>} |
| 271 |
* @final |
| 272 |
*/ |
| 273 |
goog.debug.Logger.Level.PREDEFINED_LEVELS = [ |
| 274 |
goog.debug.Logger.Level.OFF, goog.debug.Logger.Level.SHOUT, |
| 275 |
goog.debug.Logger.Level.SEVERE, goog.debug.Logger.Level.WARNING, |
| 276 |
goog.debug.Logger.Level.INFO, goog.debug.Logger.Level.CONFIG, |
| 277 |
goog.debug.Logger.Level.FINE, goog.debug.Logger.Level.FINER, |
| 278 |
goog.debug.Logger.Level.FINEST, goog.debug.Logger.Level.ALL |
| 279 |
]; |
| 280 |
|
| 281 |
|
| 282 |
/** |
| 283 |
* A lookup map used to find the level object based on the name or value of |
| 284 |
* the level object. |
| 285 |
* @type {Object} |
| 286 |
* @private |
| 287 |
*/ |
| 288 |
goog.debug.Logger.Level.predefinedLevelsCache_ = null; |
| 289 |
|
| 290 |
|
| 291 |
/** |
| 292 |
* Creates the predefined levels cache and populates it. |
| 293 |
* @private |
| 294 |
*/ |
| 295 |
goog.debug.Logger.Level.createPredefinedLevelsCache_ = function() { |
| 296 |
goog.debug.Logger.Level.predefinedLevelsCache_ = {}; |
| 297 |
for (var i = 0, level; level = goog.debug.Logger.Level.PREDEFINED_LEVELS[i]; |
| 298 |
i++) { |
| 299 |
goog.debug.Logger.Level.predefinedLevelsCache_[level.value] = level; |
| 300 |
goog.debug.Logger.Level.predefinedLevelsCache_[level.name] = level; |
| 301 |
} |
| 302 |
}; |
| 303 |
|
| 304 |
|
| 305 |
/** |
| 306 |
* Gets the predefined level with the given name. |
| 307 |
* @param {string} name The name of the level. |
| 308 |
* @return {goog.debug.Logger.Level} The level, or null if none found. |
| 309 |
*/ |
| 310 |
goog.debug.Logger.Level.getPredefinedLevel = function(name) { |
| 311 |
if (!goog.debug.Logger.Level.predefinedLevelsCache_) { |
| 312 |
goog.debug.Logger.Level.createPredefinedLevelsCache_(); |
| 313 |
} |
| 314 |
|
| 315 |
return goog.debug.Logger.Level.predefinedLevelsCache_[name] || null; |
| 316 |
}; |
| 317 |
|
| 318 |
|
| 319 |
/** |
| 320 |
* Gets the highest predefined level <= #value. |
| 321 |
* @param {number} value Level value. |
| 322 |
* @return {goog.debug.Logger.Level} The level, or null if none found. |
| 323 |
*/ |
| 324 |
goog.debug.Logger.Level.getPredefinedLevelByValue = function(value) { |
| 325 |
if (!goog.debug.Logger.Level.predefinedLevelsCache_) { |
| 326 |
goog.debug.Logger.Level.createPredefinedLevelsCache_(); |
| 327 |
} |
| 328 |
|
| 329 |
if (value in /** @type {!Object} */ ( |
| 330 |
goog.debug.Logger.Level.predefinedLevelsCache_)) { |
| 331 |
return goog.debug.Logger.Level.predefinedLevelsCache_[value]; |
| 332 |
} |
| 333 |
|
| 334 |
for (var i = 0; i < goog.debug.Logger.Level.PREDEFINED_LEVELS.length; ++i) { |
| 335 |
var level = goog.debug.Logger.Level.PREDEFINED_LEVELS[i]; |
| 336 |
if (level.value <= value) { |
| 337 |
return level; |
| 338 |
} |
| 339 |
} |
| 340 |
return null; |
| 341 |
}; |
| 342 |
|
| 343 |
|
| 344 |
/** |
| 345 |
* Finds or creates a logger for a named subsystem. If a logger has already been |
| 346 |
* created with the given name it is returned. Otherwise a new logger is |
| 347 |
* created. If a new logger is created its log level will be configured based |
| 348 |
* on the LogManager configuration and it will configured to also send logging |
| 349 |
* output to its parent's handlers. It will be registered in the LogManager |
| 350 |
* global namespace. |
| 351 |
* |
| 352 |
* @param {string} name A name for the logger. This should be a dot-separated |
| 353 |
* name and should normally be based on the package name or class name of the |
| 354 |
* subsystem, such as goog.net.BrowserChannel. |
| 355 |
* @return {!goog.debug.Logger} The named logger. |
| 356 |
* @deprecated use {@link goog.log} instead. |
| 357 |
*/ |
| 358 |
goog.debug.Logger.getLogger = function(name) { |
| 359 |
return goog.debug.LogManager.getLogger(name); |
| 360 |
}; |
| 361 |
|
| 362 |
|
| 363 |
/** |
| 364 |
* Logs a message to profiling tools, if available. |
| 365 |
* {@see https://developers.google.com/web-toolkit/speedtracer/logging-api} |
| 366 |
* {@see http://msdn.microsoft.com/en-us/library/dd433074(VS.85).aspx} |
| 367 |
* @param {string} msg The message to log. |
| 368 |
*/ |
| 369 |
goog.debug.Logger.logToProfilers = function(msg) { |
| 370 |
// Some browsers also log timeStamp calls to the console, only log |
| 371 |
// if actually asked. |
| 372 |
if (goog.debug.Logger.ENABLE_PROFILER_LOGGING) { |
| 373 |
var msWriteProfilerMark = goog.global['msWriteProfilerMark']; |
| 374 |
if (msWriteProfilerMark) { |
| 375 |
// Logs a message to the Microsoft profiler |
| 376 |
// On IE, console['timeStamp'] may output to console |
| 377 |
msWriteProfilerMark(msg); |
| 378 |
return; |
| 379 |
} |
| 380 |
|
| 381 |
// Using goog.global, as loggers might be used in window-less contexts. |
| 382 |
var console = goog.global['console']; |
| 383 |
if (console && console['timeStamp']) { |
| 384 |
// Logs a message to Firebug, Web Inspector, SpeedTracer, etc. |
| 385 |
console['timeStamp'](msg); |
| 386 |
} |
| 387 |
} |
| 388 |
}; |
| 389 |
|
| 390 |
|
| 391 |
/** |
| 392 |
* Gets the name of this logger. |
| 393 |
* @return {string} The name of this logger. |
| 394 |
*/ |
| 395 |
goog.debug.Logger.prototype.getName = function() { |
| 396 |
return this.name_; |
| 397 |
}; |
| 398 |
|
| 399 |
|
| 400 |
/** |
| 401 |
* Adds a handler to the logger. This doesn't use the event system because |
| 402 |
* we want to be able to add logging to the event system. |
| 403 |
* @param {Function} handler Handler function to add. |
| 404 |
*/ |
| 405 |
goog.debug.Logger.prototype.addHandler = function(handler) { |
| 406 |
if (goog.debug.LOGGING_ENABLED) { |
| 407 |
if (goog.debug.Logger.ENABLE_HIERARCHY) { |
| 408 |
if (!this.handlers_) { |
| 409 |
this.handlers_ = []; |
| 410 |
} |
| 411 |
this.handlers_.push(handler); |
| 412 |
} else { |
| 413 |
goog.asserts.assert( |
| 414 |
!this.name_, 'Cannot call addHandler on a non-root logger when ' + |
| 415 |
'goog.debug.Logger.ENABLE_HIERARCHY is false.'); |
| 416 |
goog.debug.Logger.rootHandlers_.push(handler); |
| 417 |
} |
| 418 |
} |
| 419 |
}; |
| 420 |
|
| 421 |
|
| 422 |
/** |
| 423 |
* Removes a handler from the logger. This doesn't use the event system because |
| 424 |
* we want to be able to add logging to the event system. |
| 425 |
* @param {Function} handler Handler function to remove. |
| 426 |
* @return {boolean} Whether the handler was removed. |
| 427 |
*/ |
| 428 |
goog.debug.Logger.prototype.removeHandler = function(handler) { |
| 429 |
if (goog.debug.LOGGING_ENABLED) { |
| 430 |
var handlers = goog.debug.Logger.ENABLE_HIERARCHY ? |
| 431 |
this.handlers_ : |
| 432 |
goog.debug.Logger.rootHandlers_; |
| 433 |
return !!handlers && goog.array.remove(handlers, handler); |
| 434 |
} else { |
| 435 |
return false; |
| 436 |
} |
| 437 |
}; |
| 438 |
|
| 439 |
|
| 440 |
/** |
| 441 |
* Returns the parent of this logger. |
| 442 |
* @return {goog.debug.Logger} The parent logger or null if this is the root. |
| 443 |
*/ |
| 444 |
goog.debug.Logger.prototype.getParent = function() { |
| 445 |
return this.parent_; |
| 446 |
}; |
| 447 |
|
| 448 |
|
| 449 |
/** |
| 450 |
* Returns the children of this logger as a map of the child name to the logger. |
| 451 |
* @return {!Object} The map where the keys are the child leaf names and the |
| 452 |
* values are the Logger objects. |
| 453 |
*/ |
| 454 |
goog.debug.Logger.prototype.getChildren = function() { |
| 455 |
if (!this.children_) { |
| 456 |
this.children_ = {}; |
| 457 |
} |
| 458 |
return this.children_; |
| 459 |
}; |
| 460 |
|
| 461 |
|
| 462 |
/** |
| 463 |
* Set the log level specifying which message levels will be logged by this |
| 464 |
* logger. Message levels lower than this value will be discarded. |
| 465 |
* The level value Level.OFF can be used to turn off logging. If the new level |
| 466 |
* is null, it means that this node should inherit its level from its nearest |
| 467 |
* ancestor with a specific (non-null) level value. |
| 468 |
* |
| 469 |
* @param {goog.debug.Logger.Level} level The new level. |
| 470 |
*/ |
| 471 |
goog.debug.Logger.prototype.setLevel = function(level) { |
| 472 |
if (goog.debug.LOGGING_ENABLED) { |
| 473 |
if (goog.debug.Logger.ENABLE_HIERARCHY) { |
| 474 |
this.level_ = level; |
| 475 |
} else { |
| 476 |
goog.asserts.assert( |
| 477 |
!this.name_, 'Cannot call setLevel() on a non-root logger when ' + |
| 478 |
'goog.debug.Logger.ENABLE_HIERARCHY is false.'); |
| 479 |
goog.debug.Logger.rootLevel_ = level; |
| 480 |
} |
| 481 |
} |
| 482 |
}; |
| 483 |
|
| 484 |
|
| 485 |
/** |
| 486 |
* Gets the log level specifying which message levels will be logged by this |
| 487 |
* logger. Message levels lower than this value will be discarded. |
| 488 |
* The level value Level.OFF can be used to turn off logging. If the level |
| 489 |
* is null, it means that this node should inherit its level from its nearest |
| 490 |
* ancestor with a specific (non-null) level value. |
| 491 |
* |
| 492 |
* @return {goog.debug.Logger.Level} The level. |
| 493 |
*/ |
| 494 |
goog.debug.Logger.prototype.getLevel = function() { |
| 495 |
return goog.debug.LOGGING_ENABLED ? this.level_ : goog.debug.Logger.Level.OFF; |
| 496 |
}; |
| 497 |
|
| 498 |
|
| 499 |
/** |
| 500 |
* Returns the effective level of the logger based on its ancestors' levels. |
| 501 |
* @return {goog.debug.Logger.Level} The level. |
| 502 |
*/ |
| 503 |
goog.debug.Logger.prototype.getEffectiveLevel = function() { |
| 504 |
if (!goog.debug.LOGGING_ENABLED) { |
| 505 |
return goog.debug.Logger.Level.OFF; |
| 506 |
} |
| 507 |
|
| 508 |
if (!goog.debug.Logger.ENABLE_HIERARCHY) { |
| 509 |
return goog.debug.Logger.rootLevel_; |
| 510 |
} |
| 511 |
if (this.level_) { |
| 512 |
return this.level_; |
| 513 |
} |
| 514 |
if (this.parent_) { |
| 515 |
return this.parent_.getEffectiveLevel(); |
| 516 |
} |
| 517 |
goog.asserts.fail('Root logger has no level set.'); |
| 518 |
return null; |
| 519 |
}; |
| 520 |
|
| 521 |
|
| 522 |
/** |
| 523 |
* Checks if a message of the given level would actually be logged by this |
| 524 |
* logger. This check is based on the Loggers effective level, which may be |
| 525 |
* inherited from its parent. |
| 526 |
* @param {goog.debug.Logger.Level} level The level to check. |
| 527 |
* @return {boolean} Whether the message would be logged. |
| 528 |
*/ |
| 529 |
goog.debug.Logger.prototype.isLoggable = function(level) { |
| 530 |
return goog.debug.LOGGING_ENABLED && |
| 531 |
level.value >= this.getEffectiveLevel().value; |
| 532 |
}; |
| 533 |
|
| 534 |
|
| 535 |
/** |
| 536 |
* Logs a message. If the logger is currently enabled for the |
| 537 |
* given message level then the given message is forwarded to all the |
| 538 |
* registered output Handler objects. |
| 539 |
* @param {goog.debug.Logger.Level} level One of the level identifiers. |
| 540 |
* @param {goog.debug.Loggable} msg The message to log. |
| 541 |
* @param {Error|Object=} opt_exception An exception associated with the |
| 542 |
* message. |
| 543 |
*/ |
| 544 |
goog.debug.Logger.prototype.log = function(level, msg, opt_exception) { |
| 545 |
// java caches the effective level, not sure it's necessary here |
| 546 |
if (goog.debug.LOGGING_ENABLED && this.isLoggable(level)) { |
| 547 |
// Message callbacks can be useful when a log message is expensive to build. |
| 548 |
if (goog.isFunction(msg)) { |
| 549 |
msg = msg(); |
| 550 |
} |
| 551 |
|
| 552 |
this.doLogRecord_(this.getLogRecord(level, msg, opt_exception)); |
| 553 |
} |
| 554 |
}; |
| 555 |
|
| 556 |
|
| 557 |
/** |
| 558 |
* Creates a new log record and adds the exception (if present) to it. |
| 559 |
* @param {goog.debug.Logger.Level} level One of the level identifiers. |
| 560 |
* @param {string} msg The string message. |
| 561 |
* @param {Error|Object=} opt_exception An exception associated with the |
| 562 |
* message. |
| 563 |
* @return {!goog.debug.LogRecord} A log record. |
| 564 |
* @suppress {es5Strict} |
| 565 |
*/ |
| 566 |
goog.debug.Logger.prototype.getLogRecord = function(level, msg, opt_exception) { |
| 567 |
if (goog.debug.LogBuffer.isBufferingEnabled()) { |
| 568 |
var logRecord = |
| 569 |
goog.debug.LogBuffer.getInstance().addRecord(level, msg, this.name_); |
| 570 |
} else { |
| 571 |
logRecord = new goog.debug.LogRecord(level, String(msg), this.name_); |
| 572 |
} |
| 573 |
if (opt_exception) { |
| 574 |
logRecord.setException(opt_exception); |
| 575 |
} |
| 576 |
return logRecord; |
| 577 |
}; |
| 578 |
|
| 579 |
|
| 580 |
/** |
| 581 |
* Logs a message at the Logger.Level.SHOUT level. |
| 582 |
* If the logger is currently enabled for the given message level then the |
| 583 |
* given message is forwarded to all the registered output Handler objects. |
| 584 |
* @param {goog.debug.Loggable} msg The message to log. |
| 585 |
* @param {Error=} opt_exception An exception associated with the message. |
| 586 |
*/ |
| 587 |
goog.debug.Logger.prototype.shout = function(msg, opt_exception) { |
| 588 |
if (goog.debug.LOGGING_ENABLED) { |
| 589 |
this.log(goog.debug.Logger.Level.SHOUT, msg, opt_exception); |
| 590 |
} |
| 591 |
}; |
| 592 |
|
| 593 |
|
| 594 |
/** |
| 595 |
* Logs a message at the Logger.Level.SEVERE level. |
| 596 |
* If the logger is currently enabled for the given message level then the |
| 597 |
* given message is forwarded to all the registered output Handler objects. |
| 598 |
* @param {goog.debug.Loggable} msg The message to log. |
| 599 |
* @param {Error=} opt_exception An exception associated with the message. |
| 600 |
*/ |
| 601 |
goog.debug.Logger.prototype.severe = function(msg, opt_exception) { |
| 602 |
if (goog.debug.LOGGING_ENABLED) { |
| 603 |
this.log(goog.debug.Logger.Level.SEVERE, msg, opt_exception); |
| 604 |
} |
| 605 |
}; |
| 606 |
|
| 607 |
|
| 608 |
/** |
| 609 |
* Logs a message at the Logger.Level.WARNING level. |
| 610 |
* If the logger is currently enabled for the given message level then the |
| 611 |
* given message is forwarded to all the registered output Handler objects. |
| 612 |
* @param {goog.debug.Loggable} msg The message to log. |
| 613 |
* @param {Error=} opt_exception An exception associated with the message. |
| 614 |
*/ |
| 615 |
goog.debug.Logger.prototype.warning = function(msg, opt_exception) { |
| 616 |
if (goog.debug.LOGGING_ENABLED) { |
| 617 |
this.log(goog.debug.Logger.Level.WARNING, msg, opt_exception); |
| 618 |
} |
| 619 |
}; |
| 620 |
|
| 621 |
|
| 622 |
/** |
| 623 |
* Logs a message at the Logger.Level.INFO level. |
| 624 |
* If the logger is currently enabled for the given message level then the |
| 625 |
* given message is forwarded to all the registered output Handler objects. |
| 626 |
* @param {goog.debug.Loggable} msg The message to log. |
| 627 |
* @param {Error=} opt_exception An exception associated with the message. |
| 628 |
*/ |
| 629 |
goog.debug.Logger.prototype.info = function(msg, opt_exception) { |
| 630 |
if (goog.debug.LOGGING_ENABLED) { |
| 631 |
this.log(goog.debug.Logger.Level.INFO, msg, opt_exception); |
| 632 |
} |
| 633 |
}; |
| 634 |
|
| 635 |
|
| 636 |
/** |
| 637 |
* Logs a message at the Logger.Level.CONFIG level. |
| 638 |
* If the logger is currently enabled for the given message level then the |
| 639 |
* given message is forwarded to all the registered output Handler objects. |
| 640 |
* @param {goog.debug.Loggable} msg The message to log. |
| 641 |
* @param {Error=} opt_exception An exception associated with the message. |
| 642 |
*/ |
| 643 |
goog.debug.Logger.prototype.config = function(msg, opt_exception) { |
| 644 |
if (goog.debug.LOGGING_ENABLED) { |
| 645 |
this.log(goog.debug.Logger.Level.CONFIG, msg, opt_exception); |
| 646 |
} |
| 647 |
}; |
| 648 |
|
| 649 |
|
| 650 |
/** |
| 651 |
* Logs a message at the Logger.Level.FINE level. |
| 652 |
* If the logger is currently enabled for the given message level then the |
| 653 |
* given message is forwarded to all the registered output Handler objects. |
| 654 |
* @param {goog.debug.Loggable} msg The message to log. |
| 655 |
* @param {Error=} opt_exception An exception associated with the message. |
| 656 |
*/ |
| 657 |
goog.debug.Logger.prototype.fine = function(msg, opt_exception) { |
| 658 |
if (goog.debug.LOGGING_ENABLED) { |
| 659 |
this.log(goog.debug.Logger.Level.FINE, msg, opt_exception); |
| 660 |
} |
| 661 |
}; |
| 662 |
|
| 663 |
|
| 664 |
/** |
| 665 |
* Logs a message at the Logger.Level.FINER level. |
| 666 |
* If the logger is currently enabled for the given message level then the |
| 667 |
* given message is forwarded to all the registered output Handler objects. |
| 668 |
* @param {goog.debug.Loggable} msg The message to log. |
| 669 |
* @param {Error=} opt_exception An exception associated with the message. |
| 670 |
*/ |
| 671 |
goog.debug.Logger.prototype.finer = function(msg, opt_exception) { |
| 672 |
if (goog.debug.LOGGING_ENABLED) { |
| 673 |
this.log(goog.debug.Logger.Level.FINER, msg, opt_exception); |
| 674 |
} |
| 675 |
}; |
| 676 |
|
| 677 |
|
| 678 |
/** |
| 679 |
* Logs a message at the Logger.Level.FINEST level. |
| 680 |
* If the logger is currently enabled for the given message level then the |
| 681 |
* given message is forwarded to all the registered output Handler objects. |
| 682 |
* @param {goog.debug.Loggable} msg The message to log. |
| 683 |
* @param {Error=} opt_exception An exception associated with the message. |
| 684 |
*/ |
| 685 |
goog.debug.Logger.prototype.finest = function(msg, opt_exception) { |
| 686 |
if (goog.debug.LOGGING_ENABLED) { |
| 687 |
this.log(goog.debug.Logger.Level.FINEST, msg, opt_exception); |
| 688 |
} |
| 689 |
}; |
| 690 |
|
| 691 |
|
| 692 |
/** |
| 693 |
* Logs a LogRecord. If the logger is currently enabled for the |
| 694 |
* given message level then the given message is forwarded to all the |
| 695 |
* registered output Handler objects. |
| 696 |
* @param {goog.debug.LogRecord} logRecord A log record to log. |
| 697 |
*/ |
| 698 |
goog.debug.Logger.prototype.logRecord = function(logRecord) { |
| 699 |
if (goog.debug.LOGGING_ENABLED && this.isLoggable(logRecord.getLevel())) { |
| 700 |
this.doLogRecord_(logRecord); |
| 701 |
} |
| 702 |
}; |
| 703 |
|
| 704 |
|
| 705 |
/** |
| 706 |
* Logs a LogRecord. |
| 707 |
* @param {goog.debug.LogRecord} logRecord A log record to log. |
| 708 |
* @private |
| 709 |
*/ |
| 710 |
goog.debug.Logger.prototype.doLogRecord_ = function(logRecord) { |
| 711 |
if (goog.debug.Logger.ENABLE_PROFILER_LOGGING) { |
| 712 |
goog.debug.Logger.logToProfilers('log:' + logRecord.getMessage()); |
| 713 |
} |
| 714 |
if (goog.debug.Logger.ENABLE_HIERARCHY) { |
| 715 |
var target = this; |
| 716 |
while (target) { |
| 717 |
target.callPublish_(logRecord); |
| 718 |
target = target.getParent(); |
| 719 |
} |
| 720 |
} else { |
| 721 |
for (var i = 0, handler; handler = goog.debug.Logger.rootHandlers_[i++];) { |
| 722 |
handler(logRecord); |
| 723 |
} |
| 724 |
} |
| 725 |
}; |
| 726 |
|
| 727 |
|
| 728 |
/** |
| 729 |
* Calls the handlers for publish. |
| 730 |
* @param {goog.debug.LogRecord} logRecord The log record to publish. |
| 731 |
* @private |
| 732 |
*/ |
| 733 |
goog.debug.Logger.prototype.callPublish_ = function(logRecord) { |
| 734 |
if (this.handlers_) { |
| 735 |
for (var i = 0, handler; handler = this.handlers_[i]; i++) { |
| 736 |
handler(logRecord); |
| 737 |
} |
| 738 |
} |
| 739 |
}; |
| 740 |
|
| 741 |
|
| 742 |
/** |
| 743 |
* Sets the parent of this logger. This is used for setting up the logger tree. |
| 744 |
* @param {goog.debug.Logger} parent The parent logger. |
| 745 |
* @private |
| 746 |
*/ |
| 747 |
goog.debug.Logger.prototype.setParent_ = function(parent) { |
| 748 |
this.parent_ = parent; |
| 749 |
}; |
| 750 |
|
| 751 |
|
| 752 |
/** |
| 753 |
* Adds a child to this logger. This is used for setting up the logger tree. |
| 754 |
* @param {string} name The leaf name of the child. |
| 755 |
* @param {goog.debug.Logger} logger The child logger. |
| 756 |
* @private |
| 757 |
*/ |
| 758 |
goog.debug.Logger.prototype.addChild_ = function(name, logger) { |
| 759 |
this.getChildren()[name] = logger; |
| 760 |
}; |
| 761 |
|
| 762 |
|
| 763 |
/** |
| 764 |
* There is a single global LogManager object that is used to maintain a set of |
| 765 |
* shared state about Loggers and log services. This is loosely based on the |
| 766 |
* java class java.util.logging.LogManager. |
| 767 |
* @const |
| 768 |
*/ |
| 769 |
goog.debug.LogManager = {}; |
| 770 |
|
| 771 |
|
| 772 |
/** |
| 773 |
* Map of logger names to logger objects. |
| 774 |
* |
| 775 |
* @type {!Object<string, !goog.debug.Logger>} |
| 776 |
* @private |
| 777 |
*/ |
| 778 |
goog.debug.LogManager.loggers_ = {}; |
| 779 |
|
| 780 |
|
| 781 |
/** |
| 782 |
* The root logger which is the root of the logger tree. |
| 783 |
* @type {goog.debug.Logger} |
| 784 |
* @private |
| 785 |
*/ |
| 786 |
goog.debug.LogManager.rootLogger_ = null; |
| 787 |
|
| 788 |
|
| 789 |
/** |
| 790 |
* Initializes the LogManager if not already initialized. |
| 791 |
*/ |
| 792 |
goog.debug.LogManager.initialize = function() { |
| 793 |
if (!goog.debug.LogManager.rootLogger_) { |
| 794 |
goog.debug.LogManager.rootLogger_ = |
| 795 |
new goog.debug.Logger(goog.debug.Logger.ROOT_LOGGER_NAME); |
| 796 |
goog.debug.LogManager.loggers_[goog.debug.Logger.ROOT_LOGGER_NAME] = |
| 797 |
goog.debug.LogManager.rootLogger_; |
| 798 |
goog.debug.LogManager.rootLogger_.setLevel(goog.debug.Logger.Level.CONFIG); |
| 799 |
} |
| 800 |
}; |
| 801 |
|
| 802 |
|
| 803 |
/** |
| 804 |
* Returns all the loggers. |
| 805 |
* @return {!Object<string, !goog.debug.Logger>} Map of logger names to logger |
| 806 |
* objects. |
| 807 |
*/ |
| 808 |
goog.debug.LogManager.getLoggers = function() { |
| 809 |
return goog.debug.LogManager.loggers_; |
| 810 |
}; |
| 811 |
|
| 812 |
|
| 813 |
/** |
| 814 |
* Returns the root of the logger tree namespace, the logger with the empty |
| 815 |
* string as its name. |
| 816 |
* |
| 817 |
* @return {!goog.debug.Logger} The root logger. |
| 818 |
*/ |
| 819 |
goog.debug.LogManager.getRoot = function() { |
| 820 |
goog.debug.LogManager.initialize(); |
| 821 |
return /** @type {!goog.debug.Logger} */ (goog.debug.LogManager.rootLogger_); |
| 822 |
}; |
| 823 |
|
| 824 |
|
| 825 |
/** |
| 826 |
* Finds a named logger. |
| 827 |
* |
| 828 |
* @param {string} name A name for the logger. This should be a dot-separated |
| 829 |
* name and should normally be based on the package name or class name of the |
| 830 |
* subsystem, such as goog.net.BrowserChannel. |
| 831 |
* @return {!goog.debug.Logger} The named logger. |
| 832 |
*/ |
| 833 |
goog.debug.LogManager.getLogger = function(name) { |
| 834 |
goog.debug.LogManager.initialize(); |
| 835 |
var ret = goog.debug.LogManager.loggers_[name]; |
| 836 |
return ret || goog.debug.LogManager.createLogger_(name); |
| 837 |
}; |
| 838 |
|
| 839 |
|
| 840 |
/** |
| 841 |
* Creates a function that can be passed to goog.debug.catchErrors. The function |
| 842 |
* will log all reported errors using the given logger. |
| 843 |
* @param {goog.debug.Logger=} opt_logger The logger to log the errors to. |
| 844 |
* Defaults to the root logger. |
| 845 |
* @return {function(Object)} The created function. |
| 846 |
*/ |
| 847 |
goog.debug.LogManager.createFunctionForCatchErrors = function(opt_logger) { |
| 848 |
return function(info) { |
| 849 |
var logger = opt_logger || goog.debug.LogManager.getRoot(); |
| 850 |
logger.severe( |
| 851 |
'Error: ' + info.message + ' (' + info.fileName + ' @ Line: ' + |
| 852 |
info.line + ')'); |
| 853 |
}; |
| 854 |
}; |
| 855 |
|
| 856 |
|
| 857 |
/** |
| 858 |
* Creates the named logger. Will also create the parents of the named logger |
| 859 |
* if they don't yet exist. |
| 860 |
* @param {string} name The name of the logger. |
| 861 |
* @return {!goog.debug.Logger} The named logger. |
| 862 |
* @private |
| 863 |
*/ |
| 864 |
goog.debug.LogManager.createLogger_ = function(name) { |
| 865 |
// find parent logger |
| 866 |
var logger = new goog.debug.Logger(name); |
| 867 |
if (goog.debug.Logger.ENABLE_HIERARCHY) { |
| 868 |
var lastDotIndex = name.lastIndexOf('.'); |
| 869 |
var parentName = name.substr(0, lastDotIndex); |
| 870 |
var leafName = name.substr(lastDotIndex + 1); |
| 871 |
var parentLogger = goog.debug.LogManager.getLogger(parentName); |
| 872 |
|
| 873 |
// tell the parent about the child and the child about the parent |
| 874 |
parentLogger.addChild_(leafName, logger); |
| 875 |
logger.setParent_(parentLogger); |
| 876 |
} |
| 877 |
|
| 878 |
goog.debug.LogManager.loggers_[name] = logger; |
| 879 |
return logger; |
| 880 |
}; |