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#getLog 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. Method Summary
jQuery.sap.log.debug(sMessage, sDetails?, sComponent?)Creates a new debug-level entry in the log with the given message, details and calling component. jQuery.sap.log.error(sMessage, sDetails?, sComponent?)Creates a new error-level entry in the log with the given message, details and calling component. jQuery.sap.log.fatal(sMessage, sDetails?, sComponent?)Creates a new fatal-level entry in the log with the given message, details and calling component. jQuery.sap.log.info(sMessage, sDetails?, sComponent?)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.setLevel(iLogLevel, sComponent?)Defines the maximum jQuery.sap.log.Level of log entries that will be recorded. jQuery.sap.log.trace(sMessage, sDetails?, sComponent?)Creates a new trace-level entry in the log with the given message, details and calling component. jQuery.sap.log.warning(sMessage, sDetails?, sComponent?)Creates a new warning-level entry in the log with the given message, details and calling component. Method Detail
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:
| {object} | oListener | The new listener object that should be informed |
Returns:
Creates a new debug-level entry in the log with the given message, details and calling component.
Parameters:
| {string} | sMessage | Message text to display |
| {string} | sDetails?, Default: '' | Details about the message, might be omitted |
| {string} | sComponent?, Default: '' | Name of the component that produced the log entry |
Returns:
Creates a new error-level entry in the log with the given message, details and calling component.
Parameters:
| {string} | sMessage | Message text to display |
| {string} | sDetails?, Default: '' | Details about the message, might be omitted |
| {string} | sComponent?, Default: '' | Name of the component that produced the log entry |
Returns:
Creates a new fatal-level entry in the log with the given message, details and calling component.
Parameters:
| {string} | sMessage | Message text to display |
| {string} | sDetails?, Default: '' | Details about the message, might be omitted |
| {string} | sComponent?, Default: '' | Name of the component that produced the log entry |
Returns:
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:
| {string} | sComponent? | Name of the component to retrieve the log level for |
- Since:
- 1.1.2
Returns:
| {int} | The log level for the given component or the default log level |
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
- Since:
- 1.1.2
Returns:
| {object[]} | an array containing the recorded log entries |
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:
| {string} | sComponent | Component to create the logger for |
| {int} | iDefaultLogLevel? | a default log level to be used for the component, if no log level has been defined for it so far. |
- Since:
- 1.1.2
Returns:
Creates a new info-level entry in the log with the given message, details and calling component.
Parameters:
| {string} | sMessage | Message text to display |
| {string} | sDetails?, Default: '' | Details about the message, might be omitted |
| {string} | sComponent?, Default: '' | Name of the component that produced the log entry |
Returns:
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:
| {int} | iLevel?, Default: Level.DEBUG | The log level in question |
| {string} | sComponent? | Name of the component to check the log level for |
- Since:
- 1.13.2
Returns:
| {boolean} | Whether logging is enabled or not |
Allows to remove a registered LogListener.
Parameters:
| {object} | oListener | The new listener object that should be removed |
Returns:
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.Level} | iLogLevel | The new log level |
| {string} | sComponent? | The log component to set the log level for |
Returns:
Creates a new trace-level entry in the log with the given message, details and calling component.
Parameters:
| {string} | sMessage | Message text to display |
| {string} | sDetails?, Default: '' | Details about the message, might be omitted |
| {string} | sComponent?, Default: '' | Name of the component that produced the log entry |
Returns:
Creates a new warning-level entry in the log with the given message, details and calling component.
Parameters:
| {string} | sMessage | Message text to display |
| {string} | sDetails?, Default: '' | Details about the message, might be omitted |
| {string} | sComponent?, Default: '' | Name of the component that produced the log entry |
Returns:
jQuery.sap.log.getLog()
Retrieves the currently recorded log entries.
- Deprecated:
- Since 1.1.2. To avoid confusion with getLogger, this method has been renamed to jQuery.sap.log.getLogEntries.