sproutcore 1.4.5-java → 1.5.0-java

data/lib/frameworks/sproutcore/frameworks/runtime/system/logger.js

@@ -1,7 +1,18 @@
 // ==========================================================================
-// SC.Logger
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2011 Strobe Inc. and contributors.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
+sc_require('ext/function');
+
+// ..........................................................
+// CONSTANTS
+//
+
+// Implementation note:  We use two spaces after four-letter prefixes and one
+// after five-letter prefixes so things align in monospaced consoles.
 
 /**
   If {@link SC.Logger.format} is true, this delimiter will be put between arguments.
@@ -24,7 +35,7 @@ SC.LOGGER_LOG_ERROR = "ERROR: ";
 
   @property {String}
 */
-SC.LOGGER_LOG_INFO = "INFO: ";
+SC.LOGGER_LOG_INFO = "INFO:  ";
 
 /**
   If {@link SC.Logger.warn} falls back onto {@link SC.Logger.log}, this will be
@@ -32,7 +43,7 @@ SC.LOGGER_LOG_INFO = "INFO: ";
 
   @property {String}
 */
-SC.LOGGER_LOG_WARN = "WARNING: ";
+SC.LOGGER_LOG_WARN = "WARN:  ";
 
 /**
   If {@link SC.Logger.debug} falls back onto {@link SC.Logger.log}, this will be
@@ -42,9 +53,83 @@ SC.LOGGER_LOG_WARN = "WARNING: ";
 */
 SC.LOGGER_LOG_DEBUG = "DEBUG: ";
 
+/**
+  If {@link SC.Logger.group} falls back onto {@link SC.Logger.log}, this will
+  be prepended to the output.
+
+  @property {String}
+*/
+SC.LOGGER_LOG_GROUP_HEADER = "** %@";       // The variable is the group title
+
+/**
+  If the reporter does not support group(), then we’ll add our own indentation
+  to our output.  This constant represents one level of indentation.
+
+  @property {String}
+*/
+SC.LOGGER_LOG_GROUP_INDENTATION = "    ";
+
+/**
+  When reporting recorded log messages, the timestamp is included with this
+  prefix.
+
+  @property {String}
+*/
+SC.LOGGER_RECORDED_LOG_TIMESTAMP_PREFIX = "%@:  ";
+
+
+SC.LOGGER_LEVEL_DEBUG = 'debug';
+SC.LOGGER_LEVEL_INFO  = 'info';
+SC.LOGGER_LEVEL_WARN  = 'warn';
+SC.LOGGER_LEVEL_ERROR = 'error';
+SC.LOGGER_LEVEL_NONE  = 'none';
+
+
+
 /** @class
 
   Object to allow for safe logging actions, such as using the browser console.
+  In addition to being output to the console, logs can be optionally recorded
+  in memory, to be accessed by your application as appropriate.
+
+  This class also adds in the concept of a “current log level”, which allows
+  your application to potentially determine a subset of logging messages to
+  output and/or record.  The order of levels is:
+
+    -  debug        SC.LOGGER_LEVEL_DEBUG
+    -  info         SC.LOGGER_LEVEL_INFO
+    -  warn         SC.LOGGER_LEVEL_WARN
+    -  error        SC.LOGGER_LEVEL_ERROR
+
+  All messages at the level or “above” will be output/recorded.  So, for
+  example, if you set the level to 'info', all 'info', 'warn', and 'error'
+  messages will be output/recorded, but no 'debug' messages will be.  Also,
+  there are two separate log levels:  one for output, and one for recording.
+  You may wish to only output, say, 'warn' and above, but record everything
+  from 'debug' on up.  (You can also limit the number log messages to record.)
+
+  This mechanism allows your application to avoid needless output (which has a
+  non-zero cost in many browsers) in the general case, but turning up the log
+  level when necessary for debugging.  Note that there can still be a
+  performance cost for preparing log messages (calling {@link String.fmt},
+  etc.), so it’s still a good idea to be selective about what log messages are
+  output even to 'debug', especially in hot code.
+
+  Similarly, you should be aware that if you wish to log objects without
+  stringification — using the {@link SC.Logger.debugWithoutFmt} variants — and
+  you enable recording, the “recorded messages” array will hold onto a
+  reference to the arguments, potentially increasing the amount of memory
+  used.
+
+  As a convenience, this class also adds some shorthand methods to SC:
+
+    -  SC.debug()   ==>   SC.Logger.debug()
+    -  SC.info()    ==>   SC.Logger.info()
+    -  SC.warn()    ==>   SC.Logger.warn()
+    -  SC.error()   ==>   SC.Logger.error()
+
+  …although note that no shorthand versions exist for the less-common
+  functions, such as defining groups.
 
   The FireFox plugin Firebug was used as a function reference. Please see
   {@link <a href="http://getfirebug.com/logging.html">Firebug Logging Reference</a>}
@@ -52,401 +137,1449 @@ SC.LOGGER_LOG_DEBUG = "DEBUG: ";
 
   @author Colin Campbell
   @author Benedikt Böhm
+  @author William Kakes
   @extends SC.Object
-  @since Sproutcore 1.0
+  @since SproutCore 1.0
   @see <a href="http://getfirebug.com/logging.html">Firebug Logging Reference</a>
 */
-SC.Logger = SC.Object.create({
+SC.Logger = SC.Object.create(
+	/** @scope SC.Logger.prototype */{
 
   // ..........................................................
   // PROPERTIES
   //
 
   /**
-    Whether or not to enable debug logging.
+    The current log level determining what is output to the reporter object
+    (usually your browser’s console).  Valid values are:
 
-    @property: {Boolean}
+      -  SC.LOGGER_LEVEL_DEBUG
+      -  SC.LOGGER_LEVEL_INFO
+      -  SC.LOGGER_LEVEL_WARN
+      -  SC.LOGGER_LEVEL_ERROR
+      -  SC.LOGGER_LEVEL_NONE
+
+    If you do not specify this value, it will default to SC.LOGGER_LEVEL_DEBUG
+    when running in development mode and SC.LOGGER_LEVEL_INFO when running in
+    production mode.
+
+    @property: {Constant}
   */
-  debugEnabled: NO,
+  logOutputLevel: null,        // If null, set appropriately during init()
+
 
   /**
-    Computed property that checks for the existence of the reporter object.
+    The current log level determining what is output to the reporter object
+    (usually your browser’s console).  Valid values are the same as with
+    'logOutputLevel':
 
-    @property {Boolean}
+      -  SC.LOGGER_LEVEL_DEBUG
+      -  SC.LOGGER_LEVEL_INFO
+      -  SC.LOGGER_LEVEL_WARN
+      -  SC.LOGGER_LEVEL_ERROR
+      -  SC.LOGGER_LEVEL_NONE
+
+    If you do not specify this value, it will default to SC.LOGGER_LEVEL_NONE.
+
+    @property: {Constant}
   */
-  exists: function() {
-    return typeof(this.get('reporter')) !== 'undefined' && this.get('reporter') != null;
-  }.property('reporter').cacheable(),
+  logRecordingLevel: SC.LOGGER_LEVEL_NONE,
+
 
   /**
-    If console.log does not exist, SC.Logger will use window.alert instead.
+    All recorded log messages.  You generally should not need to interact with
+    this array, as most commonly-used functionality can be achieved via the
+    {@link SC.Logger.outputRecordedLogMessages} and
+    {@link SC.Logger.stringifyRecordedLogMessages} methods.
+
+    This array will be lazily created when the first message is recorded.
+
+    Format:
+
+    For efficiency, each entry in the array is a simple hash rather than a
+    full SC.Object instance.  Furthermore, to minimize memory usage, niceties
+    like “type of entry: message” are avoided; if you need to parse this
+    structure, you can determine which type of entry you’re looking at by
+    checking for the 'message' and 'indentation' fields.
+<pre>
+    Log entry:
+    {
+      type:               {Constant}     (SC.LOGGER_LEVEL_DEBUG, etc.)
+      message:            {String | Boolean}
+      originalArguments:  {Arguments}    // optional
+      timestamp:          {Date}
+    }
+    
+    Group entry (either beginning or end of):
+    {
+      type:         {Constant}     SC.LOGGER_LEVEL_DEBUG, etc.
+      indentation:  {Number}       The value is the new group indentation level
+      beginGroup:   {Boolean}      Whether this entry is the beginning of a new group (as opposed to the end)
+      title:        {String}       Optional for new groups, and never present for end-of-group
+      timestamp:    {Date}
+    }
+</pre>
+
+    @property {Array}
+  */
+  recordedLogMessages: null,
 
-    This property is only used inside {@link SC.Logger.log}. If fallBackOnLog is
-    false and you call a different function, an alert will not be opened.
 
-    @property {Boolean}
+  /**
+    If the recording level is set such that messages will be recorded, this is
+    the maximum number of messages that will be saved in the
+    'recordedLogMessages' array.  Any further recorded messages will push
+    older messages out of the array, so the most recent messages will be
+    saved.
+
+    @property {Number}
   */
-  fallBackOnAlert: NO,
+  recordedLogMessagesMaximumLength: 500,
+
+
+  /**
+    If the recording level is set such that messages will be recorded, this is
+    the minimum number of messages that will be saved whenever the recordings
+    are pruned.  (They are pruned whenever you hit the maximum length, as
+    specified via the 'recordedLogMessagesMaximumLength' property.  This
+    mechanism avoids thrashing the array for each log message once the
+    maximum is reached.)  When pruning, the most recent messages will be saved.
+
+    @property {Number}
+  */
+  recordedLogMessagesPruningMinimumLength: 100,
+
+
+  /**
+    Whether or not to enable debug logging.  This property exists for
+    backwards compatibility with previous versions of SC.Logger.  In newer
+    code, you should instead set the appropriate output/recording log levels.
+
+    If this property is set to YES, it will set 'logOutputLevel' to
+    SC.LOGGER_LEVEL_DEBUG.  Otherwise, it will have no effect.
+
+    @deprecated
+    @property: {Boolean}
+  */
+  debugEnabled: NO,
+
 
   /**
-    If some function, such as console.dir, does not exist,
-    SC.Logger will try console.log if this is true.
+    Computed property that checks for the existence of the reporter object.
 
     @property {Boolean}
   */
-  fallBackOnLog: YES,
+  exists: function() {
+    return !SC.none(this.get('reporter'));
+  }.property('reporter').cacheable(),
+
 
   /**
-    Whether or not to format multiple arguments together
-    or let the browser deal with that.
+    If console.log does not exist, SC.Logger will use window.alert instead
+    when {@link SC.Logger.log} is invoked.
+
+    Note that this property has no effect for messages initiated via the
+    debug/info/warn/error methods, on the assumption that it is better to
+    simply utilize the message recording mechanism than put up a bunch of
+    alerts when there is no browser console.
 
     @property {Boolean}
   */
-  format: YES,
+  fallBackOnAlert: NO,
+
 
   /**
     The reporter is the object which implements the actual logging functions.
 
-    @default The browser's console
+    @default The browser’s console
     @property {Object}
   */
   reporter: console,
 
+
+
+
   // ..........................................................
   // METHODS
   //
 
   /**
-    Log output to the console, but only if it exists.
+    Logs a debug message to the console and potentially to the recorded
+    array, provided the respective log levels are set appropriately.
+
+    The first argument must be a string, and if there are any additional
+    arguments, it is assumed to be a format string.  Thus, you can (and
+    should) use it like:
+
+        SC.Logger.debug("%@:  My debug message", this);       // good
+
+    …and not:
+
+        SC.Logger.debug("%@:  My debug message".fmt(this));        // bad
+
+    The former method can be more efficient because if the log levels are set
+    in such a way that the debug() invocation will be ignored, then the
+    String.fmt() call will never actually be performed.
+
+    @param {String}              A message or a format string
+    @param {…}       (optional)  Other arguments to pass to String.fmt() when using a format string
+  */
+  debug: function(message, optionalFormatArgs) {
+    // Implementation note:  To avoid having to put the SC.debug() shorthand
+    // variant inside a function wrapper, we'll avoid 'this'.
+    SC.Logger._handleMessage(SC.LOGGER_LEVEL_DEBUG, YES, message, arguments);
+  },
+
+
+  /**
+    Logs a debug message to the console and potentially to the recorded
+    array, provided the respective log levels are set appropriately.
+
+    Unlike simply debug(), this method does not try to apply String.fmt() to
+    the arguments, and instead passes them directly to the reporter (and
+    stringifies them if recording).  This can be useful if the browser formats
+    a type in a manner more useful to you than you can achieve with
+    String.fmt().
 
     @param {String|Array|Function|Object}
-    @returns {Boolean} true if reporter.log exists, false otherwise
   */
-  log: function() {
-    var reporter = this.get('reporter');
+  debugWithoutFmt: function() {
+    this._handleMessage(SC.LOGGER_LEVEL_DEBUG, NO, null, arguments);
+  },
 
-    // log through the reporter
-    if (this.get('exists') && typeof(reporter.log) === "function") {
-      if (this.get('format')) {
-        reporter.log(this._argumentsToString.apply(this, arguments));
-      }
-      else {
-        reporter.log.apply(reporter, arguments);
-      }
-      return true;
-    }
 
-    // log through alert
-    else if (this.fallBackOnAlert) {
-      var s = this.get('format') ? this._argumentsToString.apply(this, arguments) : arguments;
-      // include support for overriding the alert through the reporter
-      // if it has come this far, it's likely this will fail
-      if (this.get('exists') && typeof(reporter.alert) === "function") {
-        reporter.alert(s);
-      }
-      else {
-        alert(s);
-      }
-      return true;
-    }
-    return false;
+  /**
+    Begins a new group in the console and/or in the recorded array provided
+    the respective log levels are set to ouput/record 'debug' messages.
+    Every message after this call (at any log level) will be indented for
+    readability until a matching {@link SC.Logger.debugGroupEnd} is invoked,
+    and you can create as many levels as you want.
+
+    Assuming you are using 'debug' messages elsewhere, it is preferable to
+    group them using this method over simply {@link SC.Logger.group} — the log
+    levels could be set such that the 'debug' messages are never seen, and you
+    wouldn’t want an empty/needless group!
+
+    You can optionally provide a title for the group.  If there are any
+    additional arguments, the first argument is assumed to be a format string.
+    Thus, you can (and should) use it like:
+
+          SC.Logger.debugGroup("%@:  My debug group", this);       // good
+
+    …and not:
+
+          SC.Logger.debugGroup("%@:  My debug group".fmt(this));   // bad
+
+    The former method can be more efficient because if the log levels are set
+    in such a way that the debug() invocation will be ignored, then the
+    String.fmt() call will never actually be performed.
+
+    @param {String}  (optional)  A title or format string to display above the group
+    @param {…}       (optional)  Other arguments to pass to String.fmt() when using a format string as the title
+  */
+  debugGroup: function(message, optionalFormatArgs) {
+    // Implementation note:  To avoid having to put the SC.debugGroup()
+    // shorthand variant inside a function wrapper, we'll avoid 'this'.
+    SC.Logger._handleGroup(SC.LOGGER_LEVEL_DEBUG, message, arguments);
+  },
+
+
+  /**
+    Ends a group initiated with {@link SC.Logger.debugGroup}, provided the
+    respective output/recording log levels are set appropriately.
+
+    @see SC.Logger.debugGroup
+  */
+  debugGroupEnd: function() {
+    // Implementation note:  To avoid having to put the SC.debugGroupEnd()
+    // shorthand variant inside a function wrapper, we'll avoid 'this'.
+    SC.Logger._handleGroupEnd(SC.LOGGER_LEVEL_DEBUG);
+  },
+
+
+
+  /**
+    Logs an informational message to the console and potentially to the
+    recorded array, provided the respective log levels are set appropriately.
+
+    The first argument must be a string, and if there are any additional
+    arguments, it is assumed to be a format string.  Thus, you can (and
+    should) use it like:
+
+          SC.Logger.info("%@:  My info message", this);       // good
+
+    …and not:
+
+          SC.Logger.info("%@:  My info message".fmt(this));   // bad
+
+    The former method can be more efficient because if the log levels are set
+    in such a way that the info() invocation will be ignored, then the
+    String.fmt() call will never actually be performed.
+
+    @param {String}              A message or a format string
+    @param {…}       (optional)  Other arguments to pass to String.fmt() when using a format string
+  */
+  info: function(message, optionalFormatArgs) {
+    // Implementation note:  To avoid having to put the SC.info() shorthand
+    // variant inside a function wrapper, we'll avoid 'this'.
+    SC.Logger._handleMessage(SC.LOGGER_LEVEL_INFO, YES, message, arguments);
   },
 
+
   /**
-    Log a debug message to the console.
+    Logs an information message to the console and potentially to the recorded
+    array, provided the respective log levels are set appropriately.
 
-    Logs the response using {@link SC.Logger.log} if reporter.debug does not exist and
-    {@link SC.Logger.fallBackOnLog} is true.
+    Unlike simply info(), this method does not try to apply String.fmt() to
+    the arguments, and instead passes them directly to the reporter (and
+    stringifies them if recording).  This can be useful if the browser formats
+    a type in a manner more useful to you than you can achieve with
+    String.fmt().
 
     @param {String|Array|Function|Object}
-    @returns {Boolean} true if logged to reporter, false if not
   */
-  debug: function() {
-    var reporter = this.get('reporter');
+  infoWithoutFmt: function() {
+    this._handleMessage(SC.LOGGER_LEVEL_INFO, NO, null, arguments);
+  },
 
-    if (this.get('debugEnabled') !== YES) {
-      return false;
-    }
 
-    if (this.get('exists') && (typeof reporter.debug === "function")) {
-      reporter.debug.apply(reporter, arguments);
-      return true;
-    }
-    else if (this.fallBackOnLog) {
-      var a = this._argumentsToArray(arguments);
-      if (typeof(a.unshift) === "function") a.unshift(SC.LOGGER_LOG_DEBUG);
-      return this.log.apply(this, a);
-    }
-    return false;
+  /**
+    Begins a new group in the console and/or in the recorded array provided
+    the respective log levels are set to ouput/record 'info' messages.
+    Every message after this call (at any log level) will be indented for
+    readability until a matching {@link SC.Logger.infoGroupEnd} is invoked,
+    and you can create as many levels as you want.
+
+    Assuming you are using 'info' messages elsewhere, it is preferable to
+    group them using this method over simply {@link SC.Logger.group} — the log
+    levels could be set such that the 'info' messages are never seen, and you
+    wouldn’t want an empty/needless group!
+
+    You can optionally provide a title for the group.  If there are any
+    additional arguments, the first argument is assumed to be a format string.
+    Thus, you can (and should) use it like:
+
+          SC.Logger.infoGroup("%@:  My info group", this);       // good
+
+    …and not:
+
+          SC.Logger.infoGroup("%@:  My info group".fmt(this));   // bad
+
+    The former method can be more efficient because if the log levels are set
+    in such a way that the info() invocation will be ignored, then the
+    String.fmt() call will never actually be performed.
+
+    @param {String}  (optional)  A title or format string to display above the group
+    @param {…}       (optional)  Other arguments to pass to String.fmt() when using a format string as the title
+  */
+  infoGroup: function(message, optionalFormatArgs) {
+    // Implementation note:  To avoid having to put the SC.infoGroup()
+    // shorthand variant inside a function wrapper, we'll avoid 'this'.
+    SC.Logger._handleGroup(SC.LOGGER_LEVEL_INFO, message, arguments);
   },
 
+
   /**
-    Prints the properties of an object.
+    Ends a group initiated with {@link SC.Logger.infoGroup}, provided the
+    respective output/recording log levels are set appropriately.
 
-    Logs the object using {@link SC.Logger.log} if the reporter.dir function does not exist and
-    {@link SC.Logger.fallBackOnLog} is true.
+    @see SC.Logger.infoGroup
+  */
+  infoGroupEnd: function() {
+    // Implementation note:  To avoid having to put the SC.infoGroupEnd()
+    // shorthand variant inside a function wrapper, we'll avoid 'this'.
+    SC.Logger._handleGroupEnd(SC.LOGGER_LEVEL_INFO);
+  },
 
-    @param {Object}
-    @returns {Boolean} true if logged to console, false if not
+
+
+  /**
+    Logs a warning message to the console and potentially to the recorded
+    array, provided the respective log levels are set appropriately.
+
+    The first argument must be a string, and if there are any additional
+    arguments, it is assumed to be a format string.  Thus, you can (and
+    should) use it like:
+
+          SC.Logger.warn("%@:  My warning message", this);       // good
+
+    …and not:
+
+          SC.Logger.warn("%@:  My warning message".fmt(this));   // bad
+
+    The former method can be more efficient because if the log levels are set
+    in such a way that the warn() invocation will be ignored, then the
+    String.fmt() call will never actually be performed.
+
+    @param {String}              A message or a format string
+    @param {…}       (optional)  Other arguments to pass to String.fmt() when using a format string
   */
-  dir: function() {
-    var reporter = this.get('reporter');
+  warn: function(message, optionalFormatArgs) {
+    // Implementation note:  To avoid having to put the SC.warn() shorthand
+    // variant inside a function wrapper, we'll avoid 'this'.
+    SC.Logger._handleMessage(SC.LOGGER_LEVEL_WARN, YES, message, arguments);
 
-    if (this.get('exists') && typeof(reporter.dir) === "function") {
-      // Firebug's console.dir doesn't support multiple objects here
-      // but maybe custom reporters will
-      reporter.dir.apply(reporter, arguments);
-      return true;
-    }
-    return (this.fallBackOnLog) ? this.log.apply(this, arguments) : false;
   },
 
+
   /**
-    Prints an XML outline for any HTML or XML object.
+    Logs a warning message to the console and potentially to the recorded
+    array, provided the respective log levels are set appropriately.
 
-    Logs the object using {@link SC.Logger.log} if reporter.dirxml function does not exist and
-    {@lnk SC.Logger.fallBackOnLog} is true.
+    Unlike simply warn(), this method does not try to apply String.fmt() to
+    the arguments, and instead passes them directly to the reporter (and
+    stringifies them if recording).  This can be useful if the browser formats
+    a type in a manner more useful to you than you can achieve with
+    String.fmt().
 
-    @param {Object}
-    @returns {Boolean} true if logged to reporter, false if not
+    @param {String|Array|Function|Object}
   */
-  dirxml: function() {
-    var reporter = this.get('reporter');
+  warnWithoutFmt: function() {
+    this._handleMessage(SC.LOGGER_LEVEL_WARN, NO, null, arguments);
+  },
 
-    if (this.get('exists') && typeof(reporter.dirxml) === "function") {
-      // Firebug's console.dirxml doesn't support multiple objects here
-      // but maybe custom reporters will
-      reporter.dirxml.apply(reporter, arguments);
-      return true;
+
+  /**
+    Begins a new group in the console and/or in the recorded array provided
+    the respective log levels are set to ouput/record 'warn' messages.
+    Every message after this call (at any log level) will be indented for
+    readability until a matching {@link SC.Logger.warnGroupEnd} is invoked,
+    and you can create as many levels as you want.
+
+    Assuming you are using 'warn' messages elsewhere, it is preferable to
+    group them using this method over simply {@link SC.Logger.group} — the log
+    levels could be set such that the 'warn' messages are never seen, and you
+    wouldn’t want an empty/needless group!
+
+    You can optionally provide a title for the group.  If there are any
+    additional arguments, the first argument is assumed to be a format string.
+    Thus, you can (and should) use it like:
+
+          SC.Logger.warnGroup("%@:  My warn group", this);       // good
+
+    …and not:
+
+          SC.Logger.warnGroup("%@:  My warn group".fmt(this));   // bad
+
+    The former method can be more efficient because if the log levels are set
+    in such a way that the warn() invocation will be ignored, then the
+    String.fmt() call will never actually be performed.
+
+    @param {String}  (optional)  A title or format string to display above the group
+    @param {…}       (optional)  Other arguments to pass to String.fmt() when using a format string as the title
+  */
+  warnGroup: function(message, optionalFormatArgs) {
+    // Implementation note:  To avoid having to put the SC.warnGroup()
+    // shorthand variant inside a function wrapper, we'll avoid 'this'.
+    SC.Logger._handleGroup(SC.LOGGER_LEVEL_WARN, message, arguments);
+  },
+
+
+  /**
+    Ends a group initiated with {@link SC.Logger.warnGroup}, provided the
+    respective output/recording log levels are set appropriately.
+
+    @see SC.Logger.warnGroup
+  */
+  warnGroupEnd: function() {
+    // Implementation note:  To avoid having to put the SC.warnGroupEnd()
+    // shorthand variant inside a function wrapper, we'll avoid 'this'.
+    SC.Logger._handleGroupEnd(SC.LOGGER_LEVEL_WARN);
+  },
+
+
+  /**
+    Logs an error message to the console and potentially to the recorded
+    array, provided the respective log levels are set appropriately.
+
+    The first argument must be a string, and if there are any additional
+    arguments, it is assumed to be a format string.  Thus, you can (and
+    should) use it like:
+
+          SC.Logger.error("%@:  My error message", this);       // good
+
+    …and not:
+
+          SC.Logger.warn("%@:  My error message".fmt(this));    // bad
+
+    The former method can be more efficient because if the log levels are set
+    in such a way that the warn() invocation will be ignored, then the
+    String.fmt() call will never actually be performed.
+
+    @param {String}              A message or a format string
+    @param {…}       (optional)  Other arguments to pass to String.fmt() when using a format string
+  */
+  error: function(message, optionalFormatArgs) {
+    // Implementation note:  To avoid having to put the SC.error() shorthand
+    // variant inside a function wrapper, we'll avoid 'this'.
+    SC.Logger._handleMessage(SC.LOGGER_LEVEL_ERROR, YES, message, arguments);
+  },
+
+
+  /**
+    Logs an error message to the console and potentially to the recorded
+    array, provided the respective log levels are set appropriately.
+
+    Unlike simply error(), this method does not try to apply String.fmt() to
+    the arguments, and instead passes them directly to the reporter (and
+    stringifies them if recording).  This can be useful if the browser formats
+    a type in a manner more useful to you than you can achieve with
+    String.fmt().
+
+    @param {String|Array|Function|Object}
+  */
+  errorWithoutFmt: function() {
+    this._handleMessage(SC.LOGGER_LEVEL_ERROR, NO, null, arguments);
+  },
+
+
+  /**
+    Begins a new group in the console and/or in the recorded array provided
+    the respective log levels are set to ouput/record 'error' messages.
+    Every message after this call (at any log level) will be indented for
+    readability until a matching {@link SC.Logger.errorGroupEnd} is invoked,
+    and you can create as many levels as you want.
+
+    Assuming you are using 'error' messages elsewhere, it is preferable to
+    group them using this method over simply {@link SC.Logger.group} — the log
+    levels could be set such that the 'error' messages are never seen, and you
+    wouldn’t want an empty/needless group!
+
+    You can optionally provide a title for the group.  If there are any
+    additional arguments, the first argument is assumed to be a format string.
+    Thus, you can (and should) use it like:
+
+          SC.Logger.errorGroup("%@:  My error group", this);       // good
+
+    …and not:
+
+          SC.Logger.errorGroup("%@:  My error group".fmt(this));   // bad
+
+    The former method can be more efficient because if the log levels are set
+    in such a way that the error() invocation will be ignored, then the
+    String.fmt() call will never actually be performed.
+
+    @param {String}  (optional)  A title or format string to display above the group
+    @param {…}       (optional)  Other arguments to pass to String.fmt() when using a format string as the title
+  */
+  errorGroup: function(message, optionalFormatArgs) {
+    // Implementation note:  To avoid having to put the SC.errorGroup()
+    // shorthand variant inside a function wrapper, we'll avoid 'this'.
+    SC.Logger._handleGroup(SC.LOGGER_LEVEL_ERROR, message, arguments);
+  },
+
+
+  /**
+    Ends a group initiated with {@link SC.Logger.errorGroup}, provided the
+    respective output/recording log levels are set appropriately.
+
+    @see SC.Logger.errorGroup
+  */
+  errorGroupEnd: function() {
+    // Implementation note:  To avoid having to put the SC.errorGroupEnd()
+    // shorthand variant inside a function wrapper, we'll avoid 'this'.
+    SC.Logger._handleGroupEnd(SC.LOGGER_LEVEL_ERROR);
+  },
+
+
+
+  /**
+    This method will output all recorded log messages to the reporter.  This
+    provides a convenient way to see the messages “on-demand” without having
+    to have them always output.  The timestamp of each message will be
+    included as a prefix if you specify 'includeTimestamps' as YES, although
+    in some browsers the native group indenting can make the timestamp
+    formatting less than ideal.
+
+    @param {Boolean}  (optional)  Whether to include timestamps in the output
+  */
+  outputRecordedLogMessages: function(includeTimestamps) {
+    // If we have no reporter, there's nothing we can do.
+    if (!this.get('exists')) return;
+
+    var reporter        = this.get('reporter'),
+        entries         = this.get('recordedLogMessages'),
+        indentation     = 0,
+        timestampFormat = SC.LOGGER_RECORDED_LOG_TIMESTAMP_PREFIX,
+        i, iLen, entry, type, timestampStr, message, originalArguments,
+        output, title, newIndentation, disparity, j, jLen;
+
+    if (entries) {
+      for (i = 0, iLen = entries.length;  i < iLen;  ++i) {
+        entry        = entries[i];
+        type         = entry.type;
+
+        if (includeTimestamps) {
+          timestampStr = timestampFormat.fmt(entry.timestamp.utcFormat());
+        }
+
+        // Is this a message or a group directive?
+        message = entry.message;
+        if (message) {
+          // It's a message entry.  Were the original arguments stored?  If
+          // so, we need to use those instead of the message.
+          originalArguments = entry.originalArguments;
+          this._outputMessage(type, timestampStr, indentation, message, originalArguments);
+        }
+        else {
+          // It's a group directive.  Update our indentation appropriately.
+          newIndentation = entry.indentation;
+          title          = entry.title;
+          disparity      = newIndentation - indentation;
+
+          // If the reporter implements group() and the indentation level
+          // changes by more than 1, that implies that some earlier “begin
+          // group” / “end group” directives were pruned from the beginning of
+          // the buffer and we need to insert empty groups to compensate.
+          if (reporter.group) {
+            if (Math.abs(disparity) > 1) {
+              for (j = 0, jLen = (disparity - 1);  j < jLen;  ++j) {
+                if (disparity > 0) {
+                  reporter.group();
+                }
+                else {
+                  reporter.groupEnd();
+                }
+              }
+            }
+
+            if (disparity > 0) {
+              output = timestampStr ? timestampStr : "";
+              output += title;
+              reporter.group(output);
+            }
+            else {
+              reporter.groupEnd();
+            }
+          }
+          else {
+            // The reporter doesn't implement group()?  Then simulate it using
+            // log(), assuming it implements that.
+            if (disparity > 0) {
+              // We're beginning a group.  Output the header at an indentation
+              // that is one smaller.
+              this._outputGroup(type, timestampStr, newIndentation - 1, title);
+            }
+            // else {}  (There is no need to simulate a group ending.)
+          }
+
+          // Update our indentation.
+          indentation = newIndentation;
+        }
+      }
     }
-    return (this.fallBackOnLog) ? this.log.apply(this, arguments) : false;
   },
 
+
   /**
-    Log an error to the console
+    This method will return a string representation of all recorded log
+    messages to the reporter, which can be convenient for saving logs and so
+    forth.  The timestamp of each message will be included in the string.
+
+    If there are no recorded log messages, an empty string will be returned
+    (as opposed to null).
+
+    @returns {String}
+  */
+  stringifyRecordedLogMessages: function() {
+    var ret           = "",
+        entries       = this.get('recordedLogMessages'),
+        indentation   = 0,
+        timestampFormat = SC.LOGGER_RECORDED_LOG_TIMESTAMP_PREFIX,
+        prefixMapping = this._LOG_FALLBACK_PREFIX_MAPPING,
+        groupHeader   = SC.LOGGER_LOG_GROUP_HEADER,
+        i, iLen, entry, type, message, originalArguments, prefix, line,
+        title, newIndentation, disparity;
+
+    if (entries) {
+      for (i = 0, iLen = entries.length;  i < iLen;  ++i) {
+        entry = entries[i];
+        type  = entry.type;
+
+        // First determine the prefix.
+        prefix = timestampFormat.fmt(entry.timestamp.utcFormat());
+        prefix += prefixMapping[type] || "";
+
+        // Is this a message or a group directive?
+        message = entry.message;
+        if (message) {
+          // It's a message entry.  Were arguments used, or did we format a
+          // message?  If arguments were used, we need to stringfy those
+          // instead of using the message.
+          originalArguments = entry.originalArguments;
+          line =  prefix + this._indentation(indentation);
+          line += originalArguments ? this._argumentsToString(originalArguments) : message;
+        }
+        else {
+          // It's a group directive, so we need to update our indentation
+          // appropriately.  Also, if it's the beginning of the group and it
+          // has a title, then we need to include an appropriate header.
+          newIndentation = entry.indentation;
+          title          = entry.title;
+          disparity      = newIndentation - indentation;
+          if (disparity > 0) {
+            // We're beginning a group.  Output the header at an indentation
+            // that is one smaller.
+            line = prefix + this._indentation(indentation) + groupHeader.fmt(title);
+          }
+
+          // Update our indentation.
+          indentation = newIndentation;
+        }
+
+        // Add the line to our string.
+        ret += line + "\n";
+      }
+    }
+    return ret;
+  },
 
-    Logs the error using {@link SC.Logger.log} if reporter.error does not exist and
-    {@link SC.Logger.fallBackOnLog} is true.
+
+
+  /**
+    Log output to the console, but only if it exists.
+
+    IMPORTANT:  Unlike debug(), info(), warn(), and error(), messages sent to
+    this method do not consult the log level and will always be output.
+    Similarly, they will never be recorded.
+
+    In general, you should avoid this method and instead choose the
+    appropriate categorization for your message, choosing the appropriate
+    method.
 
     @param {String|Array|Function|Object}
-    @returns {Boolean} true if logged to reporter, false if not
+    @returns {Boolean} Whether or not anything was logged
   */
-  error: function() {
-    var reporter = this.get('reporter');
+  log: function() {
+    var reporter = this.get('reporter'),
+        ret      = NO;
 
-    if (this.get('exists') && typeof(reporter.error) === "function") {
-      reporter.error.apply(reporter, arguments);
-      return true;
+    // Log through the reporter.
+    if (this.get('exists')) {
+      if (typeof reporter.log === "function") {
+        reporter.log.apply(reporter, arguments);
+        ret = YES;
+      }
+      else if (reporter.log) {
+        // IE8 implements console.log but reports the type of console.log as
+        // "object", so we cannot use apply().  Because of this, the best we
+        // can do is call it directly with an array of our arguments.
+        reporter.log(this._argumentsToArray(arguments));
+        ret = YES;
+      }
     }
-    else if (this.fallBackOnLog) {
-      var a = this._argumentsToArray(arguments);
-      if (typeof(a.unshift) === "function") a.unshift(SC.LOGGER_LOG_ERROR);
-      return this.log.apply(this, a);
+
+    // log through alert
+    if (!ret  &&  this.get('fallBackOnAlert')) {
+      // include support for overriding the alert through the reporter
+      // if it has come this far, it's likely this will fail
+      if (this.get('exists')  &&  (typeof reporter.alert === "function")) {
+        reporter.alert(arguments);
+        ret = YES;
+      }
+      else {
+        alert(arguments);
+        ret = YES;
+      }
     }
-    return false;
+    return ret;
   },
 
+
   /**
     Every log after this call until {@link SC.Logger.groupEnd} is called
-    will be indented for readability. You can create as many levels
+    will be indented for readability.  You can create as many levels
     as you want.
 
-    @param {String} [title] An optional title to display above the group
-    @returns {Boolean} true if reporter.group exists, false otherwise
+    IMPORTANT:  Unlike debugGroup(), infoGroup(), warnGroup(), and
+    errorGroup(), this method do not consult the log level and will always
+    result in output when the reporter supports it.  Similarly, group messages
+    logged via this method will never be recorded.
+
+    @param {String}  (optional)  An optional title to display above the group
   */
-  group: function(s) {
+  group: function(title) {
     var reporter = this.get('reporter');
 
-    if (this.get('exists') && typeof(reporter.group) === "function") {
-      reporter.group(s);
-      return true;
+    if (this.get('exists')  &&  (typeof reporter.group === "function")) {
+      reporter.group(title);
     }
-    return false;
   },
 
   /**
     Ends a group declared with {@link SC.Logger.group}.
 
-    @returns {Boolean} true if the reporter.groupEnd exists, false otherwise
     @see SC.Logger.group
   */
   groupEnd: function() {
     var reporter = this.get('reporter');
 
-    if (this.get('exists') && typeof(reporter.groupEnd) === "function") {
+    if (this.get('exists')  &&  (typeof reporter.groupEnd === "function")) {
       reporter.groupEnd();
-      return true;
     }
-    return false;
   },
 
+
+
   /**
-    Log an information response to the reporter.
+    Outputs the properties of an object.
 
-    Logs the response using {@link SC.Logger.log} if reporter.info does not exist and
-    {@link SC.Logger.fallBackOnLog} is true.
+    Logs the object using {@link SC.Logger.log} if the reporter.dir function
+    does not exist.
 
-    @param {String|Array|Function|Object}
-    @returns {Boolean} true if logged to reporter, false if not
+    @param {Object}
+  */
+  dir: function() {
+    var reporter = this.get('reporter');
+
+    if (this.get('exists')  &&  (typeof reporter.dir === "function")) {
+      // Firebug's console.dir doesn't support multiple objects here
+      // but maybe custom reporters will
+      reporter.dir.apply(reporter, arguments);
+    }
+    else {
+      this.log.apply(this, arguments);
+    }
+  },
+
+
+  /**
+    Prints an XML outline for any HTML or XML object.
+
+    Logs the object using {@link SC.Logger.log} if reporter.dirxml function
+    does not exist.
+
+    @param {Object}
   */
-  info: function() {
+  dirxml: function() {
     var reporter = this.get('reporter');
 
-    if (this.get('exists') && typeof(reporter.info) === "function") {
-      reporter.info.apply(reporter, arguments);
-      return true;
+    if (this.get('exists')  &&  (typeof reporter.dirxml === "function")) {
+      // Firebug's console.dirxml doesn't support multiple objects here
+      // but maybe custom reporters will
+      reporter.dirxml.apply(reporter, arguments);
     }
-    else if (this.fallBackOnLog) {
-      var a = this._argumentsToArray(arguments);
-      if (typeof(a.unshift) === "function") a.unshift(SC.LOGGER_LOG_INFO);
-      return this.log.apply(this, a);
+    else {
+      this.log.apply(this, arguments);
     }
-    return false;
   },
 
+
+
   /**
     Begins the JavaScript profiler, if it exists. Call {@link SC.Logger.profileEnd}
     to end the profiling process and receive a report.
 
-    @returns {Boolean} true if reporter.profile exists, false otherwise
+    @param {String}     (optional)  A title to associate with the profile
+    @returns {Boolean} YES if reporter.profile exists, NO otherwise
   */
-  profile: function() {
+  profile: function(title) {
     var reporter = this.get('reporter');
 
-    if (this.get('exists') && typeof(reporter.profile) === "function") {
-      reporter.profile();
-      return true;
+    if (this.get('exists')  &&  (typeof reporter.profile === "function")) {
+      reporter.profile(title);
+      return YES;
     }
-    return false;
+    return NO;
   },
 
   /**
-    Ends the JavaScript profiler, if it exists.
+    Ends the JavaScript profiler, if it exists.  If you specify a title, the
+    profile with that title will be ended.
 
-    @returns {Boolean} true if reporter.profileEnd exists, false otherwise
+    @param {String}     (optional)  A title to associate with the profile
+    @returns {Boolean} YES if reporter.profileEnd exists, NO otherwise
     @see SC.Logger.profile
   */
-  profileEnd: function() {
+  profileEnd: function(title) {
     var reporter = this.get('reporter');
 
-    if (this.get('exists') && typeof(reporter.profileEnd) === "function") {
-      reporter.profileEnd();
-      return true;
+    if (this.get('exists')  &&  (typeof reporter.profileEnd === "function")) {
+      reporter.profileEnd(title);
+      return YES;
     }
-    return false;
+    return NO;
   },
 
+
   /**
     Measure the time between when this function is called and
     {@link SC.Logger.timeEnd} is called.
 
-    @param {String} name The name of the profile to begin
-    @returns {Boolean} true if reporter.time exists, false otherwise
+    @param {String}     The name of the profile to begin
+    @returns {Boolean} YES if reporter.time exists, NO otherwise
     @see SC.Logger.timeEnd
   */
   time: function(name) {
     var reporter = this.get('reporter');
 
-    if (this.get('exists') && typeof(reporter.time) === "function") {
+    if (this.get('exists')  &&  (typeof reporter.time === "function")) {
       reporter.time(name);
-      return true;
+      return YES;
     }
-    return false;
+    return NO;
   },
 
   /**
     Ends the profile specified.
 
-    @param {String} name The name of the profile to end
-    @returns {Boolean} true if reporter.timeEnd exists, false otherwise
+    @param {String}     The name of the profile to end
+    @returns {Boolean}  YES if reporter.timeEnd exists, NO otherwise
     @see SC.Logger.time
   */
   timeEnd: function(name) {
     var reporter = this.get('reporter');
 
-    if (this.get('exists') && typeof(reporter.timeEnd) === "function") {
+    if (this.get('exists')  &&  (typeof reporter.timeEnd === "function")) {
       reporter.timeEnd(name);
-      return true;
+      return YES;
     }
-    return false;
+    return NO;
   },
 
+
   /**
     Prints a stack-trace.
 
-    @returns {Boolean} true if reporter.trace exists, false otherwise
+    @returns {Boolean} YES if reporter.trace exists, NO otherwise
   */
   trace: function() {
     var reporter = this.get('reporter');
 
-    if (this.get('exists') && typeof(reporter.trace) === "function") {
+    if (this.get('exists')  &&  (typeof reporter.trace === "function")) {
       reporter.trace();
-      return true;
+      return YES;
     }
-    return false;
+    return NO;
   },
 
-  /**
-    Log a warning to the console.
 
-    Logs the warning using {@link SC.Logger.log} if reporter.warning does not exist and
-    {@link SC.Logger.fallBackOnLog} is true.
 
-    @param {String|Array|Function|Object}
-    @returns {Boolean} true if logged to reporter, false if not
+
+  // ..........................................................
+  // INTERNAL SUPPORT
+  //
+
+  init: function() {
+    sc_super();
+
+    // Set a reasonable default value if none has been set.
+    if (!this.get('logOutputLevel')) {
+      if (SC.buildMode === "debug") {
+        this.set('logOutputLevel', SC.LOGGER_LEVEL_DEBUG);
+      }
+      else {
+        this.set('logOutputLevel', SC.LOGGER_LEVEL_INFO);
+      }
+    }
+  
+    this.debugEnabledDidChange();
+  },
+
+
+  /** @private
+    For backwards compatibility with the older 'debugEnabled' property, set
+    our log output level to SC.LOGGER_LEVEL_DEBUG if 'debugEnabled' is set to
+    YES.
   */
-  warn: function() {
-    var reporter = this.get('reporter');
+  debugEnabledDidChange: function() {
+    if (this.get('debugEnabled')) {
+      this.set('logOutputLevel', SC.LOGGER_LEVEL_DEBUG);
+    }
+  }.observes('debugEnabled'),
+
+
+
+  /** @private
+    Outputs and/or records the specified message of the specified type if the
+    respective current log levels allow for it.  Assuming
+    'automaticallyFormat' is specified, then String.fmt() will be called
+    automatically on the message, but only if at least one of the log levels
+    is such that the result will be used.
+
+    @param {String}               type                 Expected to be SC.LOGGER_LEVEL_DEBUG, etc.
+    @param {Boolean}              automaticallyFormat  Whether or not to treat 'message' as a format string if there are additional arguments
+    @param {String}               message              Expected to a string format (for String.fmt()) if there are other arguments
+    @param {String}   (optional)  originalArguments    All arguments passed into debug(), etc. (which includes 'message'; for efficiency, we don’t copy it)
+  */
+  _handleMessage: function(type, automaticallyFormat, message, originalArguments) {
+    // Are we configured to show this type?
+    var shouldOutput = this._shouldOutputType(type),
+        shouldRecord = this._shouldRecordType(type),
+        hasOtherArguments, i, len, args, output, entry;
+
+    // If we're neither going to output nor record the message, then stop now.
+    if (!(shouldOutput || shouldRecord)) return;
+
+    // Do we have arguments other than 'message'?  (Remember that
+    // 'originalArguments' contains the message here, too, hence the > 1.)
+    hasOtherArguments = (originalArguments  &&  originalArguments.length > 1);
+
+    // If we're automatically formatting and there is no message (or it is
+    // not a string), then don't automatically format after all.
+    if (automaticallyFormat  &&  (SC.none(message)  ||  (typeof message !== "string"))) {
+      automaticallyFormat = NO;
+    }
 
-    if (this.get('exists') && typeof(reporter.warn) === "function") {
-      reporter.warn.apply(reporter, arguments);
-      return true;
+    // If we should automatically format, and the client specified other
+    // arguments in addition to the message, then we'll call .fmt() assuming
+    // that the message is a format string.
+    if (automaticallyFormat) {
+      if (hasOtherArguments) {
+        args = [];
+        for (i = 1, len = originalArguments.length;  i < len;  ++i) {
+          args.push(originalArguments[i]);
+        }
+        message = message.fmt.apply(message, args);
+      }
     }
-    else if (this.fallBackOnLog) {
-      var a = this._argumentsToArray(arguments);
-      if (typeof(a.unshift) === "function") a.unshift(SC.LOGGER_LOG_WARN);
-      return this.log.apply(this, a);
+
+    if (shouldOutput) {
+      // We only want to pass the original arguments to _outputMessage() if we
+      // didn't format the message ourselves.
+      args = automaticallyFormat ? null : originalArguments;
+      this._outputMessage(type, null, this._outputIndentationLevel, message, args);
+    }
+
+    // If we're recording the log, append the message now.
+    if (shouldRecord) {
+      entry = {
+        type:      type,
+        message:   message ? message : YES,
+        timestamp: new Date()
+      };
+
+      // If we didn't automatically format, and we have other arguments, then
+      // be sure to record them, too.
+      if (!automaticallyFormat  &&  hasOtherArguments) {
+        entry.originalArguments = originalArguments;
+      }
+
+      this._addRecordedMessageEntry(entry);
     }
-    return false;
   },
 
-  // ..........................................................
-  // INTERNAL SUPPORT
-  //
 
-  /**
-    @private
+  /** @private
+    Outputs and/or records a group with the (optional) specified title
+    assuming the respective current log levels allow for it.  This will output
+    the title (if there is one) and indent all further messages (of any type)
+    until _handleGroupEnd() is invoked.
+
+    If additional arguments beyond a title are passed in, then String.fmt()
+    will be called automatically on the title, but only if at least one of the
+    log levels is such that the result will be used.
+
+    @param {String}              type                 Expected to be SC.LOGGER_LEVEL_DEBUG, etc.
+    @param {String}  (optional)  title                Expected to a string format (for String.fmt()) if there are other arguments
+    @param {String}  (optional)  originalArguments    All arguments passed into debug(), etc. (which includes 'title'; for efficiency, we don’t copy it)
+  */
+  _handleGroup: function(type, title, originalArguments) {
+    // Are we configured to show this type?
+    var shouldOutput = this._shouldOutputType(type),
+        shouldRecord = this._shouldRecordType(type),
+        hasOtherArguments, i, len, args, arg, reporter, func, header, output,
+        indentation, entry;
+
+    // If we're neither going to output nor record the group, then stop now.
+    if (!(shouldOutput || shouldRecord)) return;
+
+    // Do we have arguments other than 'title'?  (Remember that
+    // 'originalArguments' contains the title here, too, hence the > 1.)
+    hasOtherArguments = (originalArguments  &&  originalArguments.length > 1);
+
+    // If the client specified a title as well other arguments, then we'll
+    // call .fmt() assuming that the title is a format string.
+    if (title  &&  hasOtherArguments) {
+      args = [];
+      for (i = 1, len = originalArguments.length;  i < len;  ++i) {
+        args.push(originalArguments[i]);
+      }
+      title = title.fmt.apply(title, args);
+    }
+
+    if (shouldOutput) {
+      this._outputGroup(type, null, this._outputIndentationLevel, title);
+
+      // Increase our indentation level to accommodate the group.
+      this._outputIndentationLevel++;
+    }
+
+    // If we're recording the group, append the entry now.
+    if (shouldRecord) {
+      // Increase our indentation level to accommodate the group.
+      indentation = ++this._recordingIndentationLevel;
+
+      entry = {
+        type:         type,
+        indentation:  indentation,
+        beginGroup:   YES,
+        title:        title,
+        timestamp:    new Date()
+      };
+
+      this._addRecordedMessageEntry(entry);
+    }
+  },
+
+
+  /** @private
+    Outputs and/or records a “group end” assuming the respective current log
+    levels allow for it.  This will remove one level of indentation from all
+    further messages (of any type).
+
+    @param {String}              type                 Expected to be SC.LOGGER_LEVEL_DEBUG, etc.
+  */
+  _handleGroupEnd: function(type) {
+    // Are we configured to show this type?
+    var shouldOutput = this._shouldOutputType(type),
+        shouldRecord = this._shouldRecordType(type),
+        reporter, func, indentation, entry;
+
+    // If we're neither going to output nor record the "group end", then stop
+    // now.
+    if (!(shouldOutput || shouldRecord)) return;
+
+    if (shouldOutput) {
+      // Decrease our indentation level to accommodate the group.
+      this._outputIndentationLevel--;
+      
+      if (this.get('exists')) {
+        // Do we have reporter.groupEnd defined as a function?  If not, we
+        // simply won't output anything.
+        reporter = this.get('reporter');
+        func     = reporter.groupEnd;
+        if (func) {
+          func.call(reporter);
+        }
+      }
+    }
+
+    // If we're recording the “group end”, append the entry now.
+    if (shouldRecord) {
+      // Decrease our indentation level to accommodate the group.
+      indentation = --this._recordingIndentationLevel;
 
+      entry = {
+        type:         type,
+        indentation:  indentation,
+        timestamp:    new Date()
+      };
+
+      this._addRecordedMessageEntry(entry);
+    }
+  },
+
+
+  /** @private
+    Returns whether a message of the specified type ('debug', etc.) should be
+    output to the reporter based on the current value of 'logOutputLevel'.
+
+    @param {Constant}  type
+    @returns {Boolean}
+  */
+  _shouldOutputType: function(type) {
+    var logLevelMapping = this._LOG_LEVEL_MAPPING,
+        level           = logLevelMapping[type]                        ||  0,
+        currentLevel    = logLevelMapping[this.get('logOutputLevel')]  ||  0;
+
+    return (level <= currentLevel);
+  },
+
+
+  /** @private
+    Returns whether a message of the specified type ('debug', etc.) should be
+    recorded based on the current value of 'logRecordingLevel'.
+
+    @param {Constant}  type
+    @returns {Boolean}
+  */
+  _shouldRecordType: function(type) {
+    // This is the same code as in _shouldOutputType(), but inlined to
+    // avoid yet another function call.
+    var logLevelMapping = this._LOG_LEVEL_MAPPING,
+        level           = logLevelMapping[type]                           ||  0,
+        currentLevel  = logLevelMapping[this.get('logRecordingLevel')]  ||  0;
+
+    return (level <= currentLevel);
+  },
+
+
+  /** @private
+    Outputs the specified message to the current reporter.  If the reporter
+    does not handle the specified type of message, it will fall back to using
+    log() if possible.
+
+    @param {Constant}               type
+    @param {String}                 timestampStr       An optional timestamp prefix for the line, or null for none
+    @param {Number}                 indentation        The current indentation level
+    @param {String}                 message
+    @param {Arguments}  (optional)  originalArguments  If specified, the assumption is that the message was not automatically formatted
+  */
+  _outputMessage: function(type, timestampStr, indentation, message, originalArguments) {
+    if (!this.get('exists')) return;
+
+    // Do we have reporter[type] defined as a function?  If not, we'll fall
+    // back to reporter.log if that exists.
+    var reporter = this.get('reporter'),
+        output, shouldIndent, func, prefix, args, arg;
+
+    // If the reporter doesn't support group(), then we need to manually
+    // include indentation for the group.  (It it does, we'll assume that
+    // we're currently at the correct group level.)
+    shouldIndent = !reporter.group;
+
+    // Note:  Normally we wouldn't do the hash dereference twice, but
+    //        storing the result like this:
+    //
+    //          var nativeFunction = console[type];
+    //          nativeFunction(output);
+    //
+    //        …doesn't work in Safari 4, and:
+    //
+    //          nativeFunction.call(console, output);
+    //
+    //        …doesn't work in IE8 because the console.* methods are
+    //       reported as being objects.
+    func = reporter[type];
+    if (func) {
+      // If we formatted, just include the message.  Otherwise, include all
+      // the original arguments.
+      if (!originalArguments) {
+        output = "";
+        if (timestampStr) output = timestampStr;
+        if (shouldIndent) output =+ this._indentation(indentation);
+        output += message;
+        reporter[type](output);
+      }
+      else {
+        // We have arguments?  Then pass them along to the reporter function
+        // so that it can format them appropriately.  We'll use the timestamp
+        // string (if there is one) and the indentation as the first
+        // arguments.
+        args = this._argumentsToArray(originalArguments);
+        prefix = "";
+        if (timestampStr) prefix = timestampStr;
+        if (shouldIndent) prefix += this._indentation(indentation);
+        if (prefix) args.splice(0, 0, prefix);
+        
+        if (func.apply) {
+          func.apply(reporter, args);
+        }
+        else {
+          // In IE8, passing the arguments as an array isn't ideal, but it's
+          // pretty much all we can do because we can't call apply().
+          reporter[type](args);            
+        }
+      }
+    }
+    else {
+      // The reporter doesn't support the requested function?  If it at least
+      // support log(), fall back to that.
+      if (reporter.log) {
+        prefix = "";
+        if (timestampStr) prefix = timestampStr;
+        prefix += this._LOG_FALLBACK_PREFIX_MAPPING[type] || "";
+        if (shouldIndent) prefix += this._indentation(indentation);
+
+        // If we formatted, just include the message.  Otherwise, include
+        // all the original arguments.
+        if (!originalArguments) {
+          reporter.log(prefix + message);
+        }
+        else {
+          args = this._argumentsToArray(originalArguments);
+          if (prefix) args.splice(0, 0, prefix);
+          reporter.log(args);
+        }
+      }
+    }
+  },
+
+
+  /** @private
+    Outputs the specified “begin group” directive to the current reporter.  If
+    the reporter does not handle the group() method, it will fall back to
+    simulating using log() if possible.
+
+    @param {Constant}               type
+    @param {String}                 timestampStr  An optional timestamp prefix for the line, or null for none
+    @param {Number}                 indentation   The current indentation level, not including what the group will set it to
+    @param {String}     (optional)  title
+  */
+  _outputGroup: function(type, timestampStr, indentation, title) {
+    if (!this.get('exists')) return;
+
+    // Do we have reporter.group defined as a function?  If not, we'll fall
+    // back to reporter.log if that exists.  (Thankfully, we can avoid the IE8
+    // special-casing we have in _outputMessage() because IE8 doesn't support
+    // console.group(), anyway.)
+    var reporter = this.get('reporter'),
+        func     = reporter.group,
+        output;
+
+    if (func) {
+      output = timestampStr ? timestampStr : "";
+      output += title;
+      func.call(reporter, output);
+    }
+    else if (reporter.log) {
+      // The reporter doesn't support group()?  Then simulate with log().
+      // (We'll live with the duplicitous dereference rather than using
+      // apply() to work around the IE8 issue described in _outputMessage().)
+      output = "";
+      if (timestampStr) output = timestampStr;
+      output += this._LOG_FALLBACK_PREFIX_MAPPING[type] || "";
+      output += this._indentation(indentation);
+      output += SC.LOGGER_LOG_GROUP_HEADER.fmt(title);
+      reporter.log(output);
+    }
+  },
+
+
+  /** @private
+    This method will add the specified entry to the recorded log messages
+    array and also prune array as necessary according to the current values of
+    'recordedLogMessagesMaximumLength' and
+    'recordedLogMessagesPruningMinimumLength'.
+  */
+  _addRecordedMessageEntry: function(entry) {
+    var recordedMessages = this.get('recordedLogMessages'),
+        len;
+
+    // Lazily create the array.
+    if (!recordedMessages) {
+      recordedMessages = [];
+      this.set('recordedLogMessages', recordedMessages);
+    }
+
+    recordedMessages.push(entry);
+
+    // Have we exceeded the maximum size?  If so, do some pruning.
+    len = recordedMessages.length;
+    if (len > this.get('recordedLogMessagesMaximumLength')) {
+      recordedMessages.splice(0, (len - this.get('recordedLogMessagesPruningMinimumLength')));
+    }
+    
+    // Notify that the array content changed.
+    recordedMessages.enumerableContentDidChange();
+  },
+
+
+
+  /** @private
     The arguments function property doesn't support Array#unshift. This helper
     copies the elements of arguments to a blank array.
 
     @param {Array} arguments The arguments property of a function
     @returns {Array} An array containing the elements of arguments parameter
   */
-  _argumentsToArray: function(arguments) {
-    if (!arguments) return [];
-    var a = [];
-    for (var i = 0; i < arguments.length; i++) {
-      a[i] = arguments[i];
+  _argumentsToArray: function(args) {
+    var ret = [],
+        i, len;
+
+    if (args) {
+      for (i = 0, len = args.length;  i < len;  ++i) {
+        ret[i] = args[i];
+      }
     }
-    return a;
+    return ret;
   },
 
-  /**
-    @private
-
-    Formats the arguments array of a function by creating a string
-    with SC.LOGGER_LOG_DELIMITER between the elements.
 
-    @returns {String} A string of formatted arguments
+  /** @private
+    Formats the arguments array of a function by creating a string with
+    SC.LOGGER_LOG_DELIMITER between the elements.
   */
   _argumentsToString: function() {
-    var s = "";
-    for (var i = 0; i<arguments.length - 1; i++) {
-      s += arguments[i] + SC.LOGGER_LOG_DELIMITER;
+    var ret       = "",
+        delimeter = SC.LOGGER_LOG_DELIMITER,
+        i, len;
+
+    for (i = 0, len = (arguments.length - 1);  i < len;  ++i) {
+      ret += arguments[i] + delimeter;
+    }
+    ret += arguments[len];
+    return ret;
+  },
+
+
+  /** @private
+    Returns a string containing the appropriate indentation for the specified
+    indentation level.
+
+    @param {Number}  The indentation level
+    @returns {String}
+  */
+  _indentation: function(level) {
+    if (!level  ||  level < 0) {
+      level = 0;
+    }
+
+    var ret    = "",
+        indent = SC.LOGGER_LOG_GROUP_INDENTATION,
+        i;
+
+    for (i = 0;  i < level;  ++i) {
+      ret += indent;
     }
-    s += arguments[arguments.length-1];
-    return s;
+    return ret;
+  },
+
+
+
+  /** @private
+    The current “for output” indentation level.  The reporter (browser
+    console) is expected to keep track of this for us for output, but we need
+    to do our own bookkeeping if the browser doesn’t support console.group.
+    This is incremented by _debugGroup() and friends, and decremented by
+    _debugGroupEnd() and friends.
+  */
+  _outputIndentationLevel: 0,
+
+
+  /** @private
+    The current “for recording” indentation level.  This can be different than
+    the “for output” indentation level if the respective log levels are set
+    differently.  This is incremented by _debugGroup() and friends, and
+    decremented by _debugGroupEnd() and friends.
+  */
+  _recordingIndentationLevel: 0,
+
+
+  /** @private
+    A mapping of the log level constants (SC.LOGGER_LEVEL_DEBUG, etc.) to
+    their priority.  This makes it easy to determine which levels are “higher”
+    than the current level.
+
+    Implementation note:  We’re hardcoding the values of the constants defined
+    earlier here for a tiny bit of efficiency (we can create the hash all at
+    once rather than having to push in keys).
+  */
+  _LOG_LEVEL_MAPPING: { debug: 4, info: 3, warn: 2, error: 1, none: 0 },
+
+
+  /** @private
+    If the current reporter does not support a particular type of log message
+    (for example, some older browsers’ consoles support console.log but not
+    console.debug), we’ll use the specified prefixes.
+
+    Implementation note:  We’re hardcoding the values of the constants defined
+    earlier here for a tiny bit of efficiency (we can create the hash all at
+    once rather than having to push in keys).
+  */
+  _LOG_FALLBACK_PREFIX_MAPPING: {
+    debug:  SC.LOGGER_LOG_DEBUG,
+    info:   SC.LOGGER_LOG_INFO,
+    warn:   SC.LOGGER_LOG_WARN,
+    error:  SC.LOGGER_LOG_ERROR
   }
 
 });
+
+
+// Add convenient shorthands methods to SC.
+SC.debug = SC.Logger.debug;
+SC.info  = SC.Logger.info;
+SC.warn  = SC.Logger.warn;
+SC.error = SC.Logger.error;