Class: SC.Logger

Extends SC.Object.

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 Firebug Logging Reference for further information.

Defined in: logger.js

See:: <a href="http://getfirebug.com/logging.html">Firebug Logging Reference
Since:: SproutCore 1.0

Field Summary

Fields borrowed from SC.Object:: concatenatedProperties, isDestroyed, isObject, nextProperty, object, property, target, toInvalidate
Fields borrowed from SC.Observable:: isObservable

Instance Methods

Field Detail

Deprecated: Set the log level instead.

debugEnabled

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.

fallBackOnAlert Boolean

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.

logOutputLevel

The current log level determining what is output to the reporter object (usually your browser’s console). Valid values are:

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.

logRecordingLevel Constant

The current log level determining what is recorded to the 'recordedLogMessages' buffer. Valid values are the same as with 'logOutputLevel':

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.

messagePrefix String

An optional prefix that will be prepended to all log messages, but not any group titles.

outputMessagePrefix String

An optional prefix that will be prepended to all log messages that are output to the browser console, but not those that are recorded. If you specify both this and a 'messagePrefix', both will be output, and only the 'messagePrefix' will be recorded.

recordedLogMessages Array

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.

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}
}

recordedLogMessagesMaximumLength Number

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.

recordedLogMessagesPruningMinimumLength Number

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.

recordedMessagePrefix String

An optional prefix that will be prepended to all log messages that are recorded, but not those that are output to the browser console. If you specify both this and a 'messagePrefix', both will be recorded, and only the 'messagePrefix' will be output to the browser console.

reporter Object

The reporter is the object which implements the actual logging functions.

Default value:: The browser’s console

Instance Method Detail

debug(A, (optional))

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.

Parameters:
A String: message or a format string
(optional) …: Other arguments to pass to String.fmt() when using a format string

debugGroup((optional), (optional))

Begins a new group in the console and/or in the recorded array provided the respective log levels are set to output/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.

Parameters:
(optional) String: A title or format string to display above the group
(optional) …: Other arguments to pass to String.fmt() when using a format string as the title

debugGroupEnd()

Ends a group initiated with {@link SC.Logger.debugGroup}, provided the respective output/recording log levels are set appropriately.

See:: SC.Logger.debugGroup

debugWithoutFmt()

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().

Parameters:
String|Array|Function|Object

dir()

Outputs the properties of an object.

Logs the object using {@link SC.Logger.log} if the reporter.dir function does not exist.

Parameters:
Object

dirxml()

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.

Parameters:
Object

error(A, (optional))

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.

Parameters:
A String: message or a format string
(optional) …: Other arguments to pass to String.fmt() when using a format string

errorGroup((optional), (optional))

Begins a new group in the console and/or in the recorded array provided the respective log levels are set to output/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.

Parameters:
(optional) String: A title or format string to display above the group
(optional) …: Other arguments to pass to String.fmt() when using a format string as the title

errorGroupEnd()

Ends a group initiated with {@link SC.Logger.errorGroup}, provided the respective output/recording log levels are set appropriately.

See:: SC.Logger.errorGroup

errorWithoutFmt()

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().

Parameters:
String|Array|Function|Object

exists()

Computed property that checks for the existence of the reporter object.

group((optional))

Every log after this call until {@link SC.Logger.groupEnd} is called will be indented for readability. You can create as many levels as you want.

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.

Parameters:
(optional) String: An optional title to display above the group

groupEnd()

Ends a group declared with SC.Logger.group.

See:: SC.Logger.group

info(A, (optional))

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.

Parameters:
A String: message or a format string
(optional) …: Other arguments to pass to String.fmt() when using a format string

infoGroup((optional), (optional))

Begins a new group in the console and/or in the recorded array provided the respective log levels are set to output/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.

Parameters:
(optional) String: A title or format string to display above the group
(optional) …: Other arguments to pass to String.fmt() when using a format string as the title

infoGroupEnd()

Ends a group initiated with {@link SC.Logger.infoGroup}, provided the respective output/recording log levels are set appropriately.

See:: SC.Logger.infoGroup

infoWithoutFmt()

Logs an information message to the console and potentially to the recorded array, provided the respective log levels are set appropriately.

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().

Parameters:
String|Array|Function|Object

init()

log()

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.

Parameters:
String|Array|Function|Object
Returns:
Boolean: Whether or not anything was logged

outputRecordedLogMessages((optional))

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.

Parameters:
(optional) Boolean: Whether to include timestamps in the output

profile((optional))

Begins the JavaScript profiler, if it exists. Call {@link SC.Logger.profileEnd} to end the profiling process and receive a report.

Parameters:
(optional) String: A title to associate with the profile
Returns:
Boolean: YES if reporter.profile exists, NO otherwise

profileEnd((optional))

Ends the JavaScript profiler, if it exists. If you specify a title, the profile with that title will be ended.

Parameters:
(optional) String: A title to associate with the profile
Returns:
Boolean: YES if reporter.profileEnd exists, NO otherwise

See:: SC.Logger.profile

stringifyRecordedLogMessages()

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

time(The)

Measure the time between when this function is called and {@link SC.Logger.timeEnd} is called.

Parameters:
The String: name of the profile to begin
Returns:
Boolean: YES if reporter.time exists, NO otherwise

See:: SC.Logger.timeEnd

timeEnd(The)

Ends the profile specified.

Parameters:
The String: name of the profile to end
Returns:
Boolean: YES if reporter.timeEnd exists, NO otherwise

See:: SC.Logger.time

trace()

Prints a stack-trace.

Returns:
Boolean: YES if reporter.trace exists, NO otherwise

warn(A, (optional))

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.

Parameters:
A String: message or a format string
(optional) …: Other arguments to pass to String.fmt() when using a format string

warnGroup((optional), (optional))

Begins a new group in the console and/or in the recorded array provided the respective log levels are set to output/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.

Parameters:
(optional) String: A title or format string to display above the group
(optional) …: Other arguments to pass to String.fmt() when using a format string as the title

warnGroupEnd()

Ends a group initiated with {@link SC.Logger.warnGroup}, provided the respective output/recording log levels are set appropriately.

See:: SC.Logger.warnGroup

warnWithoutFmt()

Logs a warning message to the console and potentially to the recorded array, provided the respective log levels are set appropriately.

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().

Parameters:
String|Array|Function|Object

Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:20 GMT-0600 (CST)