Namespace jQuery.sap.logModule: jquery.sap.global


A Logging API for JavaScript.

Provides methods to manage a client-side log and to create entries in it. Each of the logging methods jQuery.sap.log.debug, jQuery.sap.log.info, jQuery.sap.log.warning, jQuery.sap.log.error and jQuery.sap.log.fatal creates and records a log entry, containing a timestamp, a log level, a message with details and a component info. The log level will be one of jQuery.sap.log.Level and equals the name of the concrete logging method.

By using the jQuery.sap.log.setLevel method, consumers can determine the least important log level which should be recorded. Less important entries will be filtered out. (Note that higher numeric values represent less important levels). The initially set level depends on the mode that UI5 is running in. When the optimized sources are executed, the default level will be jQuery.sap.log.Level.ERROR. For normal (debug sources), the default level is jQuery.sap.log.Level.DEBUG.

All logging methods allow to specify a component. These components are simple strings and don't have a special meaning to the UI5 framework. However they can be used to semantically group log entries that belong to the same software component (or feature). There are two APIs that help to manage logging for such a component. With jQuery.sap.log.getLogger(sComponent), one can retrieve a logger that automatically adds the given sComponent as component parameter to each log entry, if no other component is specified. Typically, JavaScript code will retrieve such a logger once during startup and reuse it for the rest of its lifecycle. Second, the jQuery.sap.log.Logger#setLevel(iLevel, sComponent) method allows to set the log level for a specific component only. This allows a more fine granular control about the created logging entries. jQuery.sap.log.Logger#getLevel allows to retrieve the currently effective log level for a given component.

jQuery.sap.log.getLogEntries returns an array of the currently collected log entries.

Furthermore, a listener can be registered to the log. It will be notified whenever a new entry is added to the log. The listener can be used for displaying log entries in a separate page area, or for sending it to some external target (server).


Since: 0.9.0.
Namespaces & Classes
LevelEnumeration of the configurable log levels that a Logger should persist to the log.
LoggerA Logger class
LogLevelEnumeration of levels that can be used in a call to jQuery.sap.log.Logger#setLevel(iLevel, sComponent).
Method Summary
jQuery.sap.log.addLogListener(oListener)Allows to add a new LogListener that will be notified for new log entries.
jQuery.sap.log.debug(sMessage, sDetails?, sComponent?, fnSupportInfo?)Creates a new debug-level entry in the log with the given message, details and calling component.
jQuery.sap.log.error(sMessage, sDetails?, sComponent?, fnSupportInfo?)Creates a new error-level entry in the log with the given message, details and calling component.
jQuery.sap.log.fatal(sMessage, sDetails?, sComponent?, fnSupportInfo?)Creates a new fatal-level entry in the log with the given message, details and calling component.
jQuery.sap.log.getLevel(sComponent?)Returns the log level currently effective for the given component.
jQuery.sap.log.getLogEntries()Returns the logged entries recorded so far as an array.
jQuery.sap.log.getLogger(sComponent, iDefaultLogLevel?)Returns a jQuery.sap.log.Logger for the given component.
jQuery.sap.log.info(sMessage, sDetails?, sComponent?, fnSupportInfo?)Creates a new info-level entry in the log with the given message, details and calling component.
jQuery.sap.log.isLoggable(iLevel?, sComponent?)Checks whether logging is enabled for the given log level, depending on the currently effective log level for the given component.
jQuery.sap.log.removeLogListener(oListener)Allows to remove a registered LogListener.
jQuery.sap.log.setLevel(iLogLevel, sComponent?)Defines the maximum jQuery.sap.log.Level of log entries that will be recorded.
jQuery.sap.log.trace(sMessage, sDetails?, sComponent?, fnSupportInfo?)Creates a new trace-level entry in the log with the given message, details and calling component.
jQuery.sap.log.warning(sMessage, sDetails?, sComponent?, fnSupportInfo?)Creates a new warning-level entry in the log with the given message, details and calling component.
jQuery.sap.log.getLog()Retrieves the currently recorded log entries.
Method Detail
jQuery.sap.log.addLogListener(oListener): jQuery.sap.log

Allows to add a new LogListener that will be notified for new log entries.

The given object must provide method onLogEntry and can also be informed about onDetachFromLog and onAttachToLog

Parameters:
objectoListenerThe new listener object that should be informed
Returns:
jQuery.sap.logThe global logger
jQuery.sap.log.debug(sMessage, sDetails?, sComponent?, fnSupportInfo?): jQuery.sap.log.Logger
Creates a new debug-level entry in the log with the given message, details and calling component.
Parameters:
stringsMessageMessage text to display
stringsDetails?, Default: ''Details about the message, might be omitted
stringsComponent?, Default: ''Name of the component that produced the log entry
functionfnSupportInfo?Callback that returns an additional support object to be logged in support mode. This function is only called if support info mode is turned on with logSupportInfo(true). To avoid negative effects regarding execution times and memory consumption, the returned object should be a simple immutable JSON object with mostly static and stable content.
Returns:
jQuery.sap.log.LoggerThe log instance
jQuery.sap.log.error(sMessage, sDetails?, sComponent?, fnSupportInfo?): jQuery.sap.log.Logger
Creates a new error-level entry in the log with the given message, details and calling component.
Parameters:
stringsMessageMessage text to display
stringsDetails?, Default: ''Details about the message, might be omitted
stringsComponent?, Default: ''Name of the component that produced the log entry
functionfnSupportInfo?Callback that returns an additional support object to be logged in support mode. This function is only called if support info mode is turned on with logSupportInfo(true). To avoid negative effects regarding execution times and memory consumption, the returned object should be a simple immutable JSON object with mostly static and stable content.
Returns:
jQuery.sap.log.LoggerThe log instance
jQuery.sap.log.fatal(sMessage, sDetails?, sComponent?, fnSupportInfo?): jQuery.sap.log.Logger
Creates a new fatal-level entry in the log with the given message, details and calling component.
Parameters:
stringsMessageMessage text to display
stringsDetails?, Default: ''Details about the message, might be omitted
stringsComponent?, Default: ''Name of the component that produced the log entry
functionfnSupportInfo?Callback that returns an additional support object to be logged in support mode. This function is only called if support info mode is turned on with logSupportInfo(true). To avoid negative effects regarding execution times and memory consumption, the returned object should be a simple immutable JSON object with mostly static and stable content.
Returns:
jQuery.sap.log.LoggerThe log instance for method chaining
jQuery.sap.log.getLevel(sComponent?): int
Returns the log level currently effective for the given component. If no component is given or when no level has been configured for a given component, the log level for the default component of this logger is returned.
Parameters:
stringsComponent?Name of the component to retrieve the log level for
Returns:
intThe log level for the given component or the default log level
Since:
1.1.2
jQuery.sap.log.getLogEntries(): object[]

Returns the logged entries recorded so far as an array.

Log entries are plain JavaScript objects with the following properties

  • timestamp {number} point in time when the entry was created
  • level {int} LogLevel level of the entry
  • message {string} message text of the entry
Returns:
object[]an array containing the recorded log entries
Since:
1.1.2
jQuery.sap.log.getLogger(sComponent, iDefaultLogLevel?): jQuery.sap.log.Logger

Returns a jQuery.sap.log.Logger for the given component.

The method might or might not return the same logger object across multiple calls. While loggers are assumed to be light weight objects, consumers should try to avoid redundant calls and instead keep references to already retrieved loggers.

The optional second parameter iDefaultLogLevel allows to specify a default log level for the component. It is only applied when no log level has been defined so far for that component (ignoring inherited log levels). If this method is called multiple times for the same component but with different log levels, only the first call one might be taken into account.

Parameters:
stringsComponentComponent to create the logger for
intiDefaultLogLevel?a default log level to be used for the component, if no log level has been defined for it so far.
Returns:
jQuery.sap.log.LoggerA logger for the component.
Since:
1.1.2
jQuery.sap.log.info(sMessage, sDetails?, sComponent?, fnSupportInfo?): jQuery.sap.log.Logger
Creates a new info-level entry in the log with the given message, details and calling component.
Parameters:
stringsMessageMessage text to display
stringsDetails?, Default: ''Details about the message, might be omitted
stringsComponent?, Default: ''Name of the component that produced the log entry
functionfnSupportInfo?Callback that returns an additional support object to be logged in support mode. This function is only called if support info mode is turned on with logSupportInfo(true). To avoid negative effects regarding execution times and memory consumption, the returned object should be a simple immutable JSON object with mostly static and stable content.
Returns:
jQuery.sap.log.LoggerThe log instance
jQuery.sap.log.isLoggable(iLevel?, sComponent?): boolean

Checks whether logging is enabled for the given log level, depending on the currently effective log level for the given component.

If no component is given, the default component of this logger will be taken into account.

Parameters:
intiLevel?, Default: Level.DEBUGThe log level in question
stringsComponent?Name of the component to check the log level for
Returns:
booleanWhether logging is enabled or not
Since:
1.13.2
jQuery.sap.log.removeLogListener(oListener): jQuery.sap.log
Allows to remove a registered LogListener.
Parameters:
objectoListenerThe new listener object that should be removed
Returns:
jQuery.sap.logThe global logger
jQuery.sap.log.setLevel(iLogLevel, sComponent?): jQuery.sap.log.Logger

Defines the maximum jQuery.sap.log.Level of log entries that will be recorded. Log entries with a higher (less important) log level will be omitted from the log. When a component name is given, the log level will be configured for that component only, otherwise the log level for the default component of this logger is set. For the global logger, the global default level is set.

Note: Setting a global default log level has no impact on already defined component log levels. They always override the global default log level.

Parameters:
jQuery.sap.log.LeveliLogLevelThe new log level
stringsComponent?The log component to set the log level for
Returns:
jQuery.sap.log.LoggerThis logger object to allow method chaining
jQuery.sap.log.trace(sMessage, sDetails?, sComponent?, fnSupportInfo?): jQuery.sap.log.Logger
Creates a new trace-level entry in the log with the given message, details and calling component.
Parameters:
stringsMessageMessage text to display
stringsDetails?, Default: ''Details about the message, might be omitted
stringsComponent?, Default: ''Name of the component that produced the log entry
functionfnSupportInfo?Callback that returns an additional support object to be logged in support mode. This function is only called if support info mode is turned on with logSupportInfo(true). To avoid negative effects regarding execution times and memory consumption, the returned object should be a simple immutable JSON object with mostly static and stable content.
Returns:
jQuery.sap.log.LoggerThe log-instance
jQuery.sap.log.warning(sMessage, sDetails?, sComponent?, fnSupportInfo?): jQuery.sap.log.Logger
Creates a new warning-level entry in the log with the given message, details and calling component.
Parameters:
stringsMessageMessage text to display
stringsDetails?, Default: ''Details about the message, might be omitted
stringsComponent?, Default: ''Name of the component that produced the log entry
functionfnSupportInfo?Callback that returns an additional support object to be logged in support mode. This function is only called if support info mode is turned on with logSupportInfo(true). To avoid negative effects regarding execution times and memory consumption, the returned object should be a simple immutable JSON object with mostly static and stable content.
Returns:
jQuery.sap.log.LoggerThe log instance
jQuery.sap.log.getLog()
Retrieves the currently recorded log entries.
Deprecated API:
Since 1.1.2. To avoid confusion with getLogger, this method has been renamed to jQuery.sap.log.getLogEntries.