Namespace: Logger

sap. Logger

The Kapsel Logger plugin provides a Cordova plugin wrapper around the SAP Mobile Platform client logging API (Supportability library).

The Logger plugin has ERROR, WARN, INFO, and DEBUG log levels and log messages are captured based on the configured and selected log level. A Kapsel application can be set to these log levels by programmatic control, and by the administrator changing a setting on the server. For Android and iOS, the default log level is ERROR, so by default only ERROR level logs are captured. sap.Logger.setLogLevel() method is used to set other levels. If you want to get log messages at all log levels, you must set the log level to DEBUG. (DEBUG < INFO < WARN < ERROR)
If the log level is set to DEBUG, the application captures all log messages.
If you set the log level to INFO, the application captures INFO, WARN, and ERROR log messages.
If you set the log level to WARN, the application captures WARN and ERROR log messages.
If you set the log level to ERROR, the application captures only Error log messages.

Using the provided sap.Logger.upload() method allows developers to upload a log file to SAP Mobile Platform Server, where an administrator can view them and remotely set the appropriate log level to control the amount of information that is written to the log. When the sap.Logger.upload() method is triggered, a log file will be uploaded. If the Log Upload checkbox is selected in the Management Cockpit, the client can upload a log file by calling sap.Logger.upload(). If the Log Upload checkbox is disabled in the Management Cockpit, the client does not upload the log file to the server. The attempt to upload causes an "HTTP/1.1 403 Forbidden" error. To support manual uploading of the log, you should implement a button or some other mechanism that calls sap.Logger.upload() when needed.
For the Logger plugin to upload a log file these conditions must be met: 1) Log Upload checkbox enabled In the Management Cockpit 2) sap.Logger.upload() is called by developer.
The expected work flow, with the current architecture consists of the following:
1) If a user has an issue that needs to be analyzed by an administrator or developer, the user reports the issue as appropriate.
2) The administrator, or developer, enables the log collection for the user on the SAP Mobile Platform server.
3) The administrator lets the user know that he, or she, can upload log file.
4) The user uploads thelog file to the server, and the administrator gets the uploaded log file in the Management Cockpit.
5) The administrator sends the file to the developer to debug.

Currently, on iOS, if the current log level is ERROR (default level), only ERROR level messages are displayed on the console even if other log level messages are generated. But if the current log level is DEBUG, INFO, or WARN, all generated log messages, regardless of log level, are displayed on the console.
On Android, if the current log level is ERROR, only ERROR level messages are displayed in the Android logcat view (console). if log level is INFO, then ERROR, WARN and INFO level messages are displayed in the Android logcat view (console).


When the Kapsel Settings plugin is added to the project, Settings will: 1) Get log level from the server 2) Set it into Logger on the client 3) Call sap.Logger.upload() after a logon success event, for example, when the app is launched or resumed and logon is successful. The Settings plugin retrieves the selected log level(type) from the Management Cockpit on the server, sets the log level to Logger plugin, and then automatically uploads a log file to the server. If the Settings plugin is not added to the project, a log file can be uploaded only by the developer calling the sap.Logger.upload() method manually. To upload a log file automatically, settings plugin is required. In the Management Cockpit, in the Client Logging dialog box, the Log Upload checkbox is able to enable or disable log file upload, and you can choose the log type(level). You can also view a list of the uploaded log files. On the server side, there are seven log types: NONE, FATAL, ERROR, WARNING, INFO, DEBUG and PATH. Since the Kapsel Logger plugin supports only DEBUG, INFO, WARN, and ERROR, the Logger plugin implicitly matches FATAL to ERROR, and PATH to DEBUG. If NONE is set in the Management Cockpit, Logger sets it to default log level.

Adding and Removing the Logger Plugin
Add or remove the Logger plugin using the Cordova CLI.

To add the Logger plugin to your project, use the following command:
Cordova plugin add kapsel-plugin-logger

To remove the Logger plugin from your project, use the following command:
cordova plugin rm kapsel-plugin-logger

Members

(static, constant) Logger#CONSOLE :String

Constant variable for log destination. It contains "CONSOLE" string.
Type:
  • String
Example
sap.Logger.setDestination([sap.Logger.CONSOLE]);

(static, constant) Logger#DEBUG :String

Constant variable for Debug log level. It contains "DEBUG" string.
Type:
  • String
Example
sap.Logger.setLogLevel(sap.Logger.DEBUG);

(static, constant) Logger#ERROR :String

Constant variable for Error log level. It contains "ERROR" string.
Type:
  • String
Example
sap.Logger.setLogLevel(sap.Logger.ERROR);

(static, constant) Logger#FILESYSTEM :String

Constant variable for log destination. It contains "FILESYSTEM" string.
Type:
  • String
Example
sap.Logger.setDestination([sap.Logger.FILESYSTEM]);

(static, constant) Logger#INFO :String

Constant variable for Information log level. It contains "INFO" string.
Type:
  • String
Example
sap.Logger.setLogLevel(sap.Logger.INFO);

(static, constant) Logger#WARN :String

Constant variable for Warning log level. It contains "WARN" string.
Type:
  • String
Example
sap.Logger.setLogLevel(sap.Logger.WARN);

(inner) local

Set the initial log level from native config. This will be the value until the setting exchange changes with what is there in the server.

Methods

(static) clearLog(successCallbackopt, errorCallbackopt)

Clear the contents of the log.
Parameters:
Name Type Attributes Description
successCallback function <optional>
Callback function called when log has been successfully cleared.
errorCallback function <optional>
Callback function called when the log has failed to be cleared.
Example
sap.Logger.clearLog();

(static) debug(message, tagopt, successCallbackopt, errorCallbackopt)

Add a debug message to the log. This function logs messages with the 'DEBUG' log level.
Parameters:
Name Type Attributes Description
message String Log message to be logged.
tag String <optional>
Tag value added to the log entry used to indicate the source of the message (for example, SMP_LOGGER, SMP_AUTHPROXY).
successCallback function <optional>
Callback function called when the message has been successfully added to the log. No object will be passed to success callback.
errorCallback function <optional>
Callback function called when an error occurs while adding the message to the log. Since Kapsel Logger native code will always call the success callback function, the errorCallback function will be executed by Cordova if an error or exception occurs while making the call to the plugin.
Example
sap.Logger.debug("debug message", "DEBUG_TAG");

(static) emailLog(toopt, subjectopt, messageopt, successCallbackopt, errorCallbackopt)

Email the contents of the log as an attachment.
Parameters:
Name Type Attributes Description
to String <optional>
email address to email log to
subject String <optional>
the subject of the email
message String <optional>
message placed in the body of the email
successCallback function <optional>
Callback function called when the devices email application has been called with the log as an attachment.
errorCallback function <optional>
Callback function called when an error occurs calling the devices email application.
Example
sap.Logger.emailLog();

sap.Logger.emailLog('joe@someserver.com','The log','Please see the attached log.');

(static) error(message, tagopt, successCallbackopt, errorCallbackopt)

Add an error message to the log. This function logs messages with the 'ERROR' log level.
Parameters:
Name Type Attributes Description
message String Log message to be logged.
tag String <optional>
Tag value added to the log entry used to indicate the source of the message (for example, SMP_LOGGER, SMP_AUTHPROXY).
successCallback function <optional>
Callback function called when the message has been successfully added to the log. No object will be passed to success callback.
errorCallback function <optional>
Callback function called when an error occurs while adding the message to the log. Since Kapsel Logger native code will always call the success callback function, the errorCallback function will be executed by Cordova if an error or exception occurs while making the call to the plugin.
Example
sap.Logger.error("error message", "ERROR_TAG");

(static) getFormattedLogEntries(successCallback, errorCallback)

Get formatted log entries. This function is the same as getLogEntries, except that the entries are formatted the same on iOS and Android. Each field is separted by a # character. This function gets the aggregated log entries from all loggers. Use this function to retrieve log entries with the given level produced during the current session till the point the API was called. (Currently, it's only for iOS. On Android, this function retrieves all log entries regardless of log level.)
Parameters:
Name Type Description
successCallback function Callback function called when the log entries have been successfully retrieved. When the current log entries are successfully retrieved, it is fired with the aggregated log entries. Log entries of String type will be passed to success callback.
errorCallback function Callback function called when an error occurs while getting the aggregated log entries.
Example
sap.Logger.getFormattedLogEntries(successCallback, errorCallback);

function successCallback(logEntries) {
    alert(logEntries);
}

function errorCallback() {
    alert("Failed to get log entries");
}

(static) getLogEntries(successCallback, errorCallback)

Get log entries. This function gets the aggregated log entries from all loggers. Use this function to retrieve log entries with the given level produced during the current session till the point the API was called. (Currently, it's only for iOS. On Android, this function retrieves all log entries regardless of log level.)
Parameters:
Name Type Description
successCallback function Callback function called when the log entries have been successfully retrieved. When the current log entries are successfully retrieved, it is fired with the aggregated log entries. Log entries of String type will be passed to success callback.
errorCallback function Callback function called when an error occurs while getting the aggregated log entries.
Example
sap.Logger.getLogEntries(successCallback, errorCallback);

function successCallback(logEntries) {
    alert(logEntries);
}

function errorCallback() {
    alert("Failed to get log entries");
}

(static) getLogLevel(successCallback, errorCallbackopt)

Get log level. This function gets the current log level. Use this function to know what kind of log level messages can be generated and affected at the current log level.
Parameters:
Name Type Attributes Description
successCallback function Callback function called when the log level has been successfully retrieved. When the current log level is successfully retrieved, it is fired with the current log level. [DEBUG, INFO, WARN, ERROR] Log level of String type will be passed to success callback. Default log level is ERROR.
errorCallback function <optional>
Callback function called when an error occurs while getting the current log level. For this method, error callback is optional. Since Kapsel Logger native code will always call the success callback function, the errorCallback function will be executed by Cordova if an error or exception occurs while making the call to the plugin.
Example
sap.Logger.getLogLevel(successCallback, errorCallback);

function successCallback(logLevel) {
    alert("Log level is " + logLevel);
}

function errorCallback() {
    alert("Failed to get log level");
}

(static) info(message, tagopt, successCallbackopt, errorCallbackopt)

Add an info message to the log. This function logs messages with the 'INFO' log level.
Parameters:
Name Type Attributes Description
message String Log message to be logged.
tag String <optional>
Tag value added to the log entry used to indicate the source of the message (for example, SMP_LOGGER, SMP_AUTHPROXY).
successCallback function <optional>
Callback function called when the message has been successfully added to the log. No object will be passed to success callback.
errorCallback function <optional>
Callback function called when an error occurs while adding the message to the log. Since Kapsel Logger native code will always call the success callback function, the errorCallback function will be executed by Cordova if an error or exception occurs while making the call to the plugin.
Example
sap.Logger.info("info message", "INFO_TAG");

(static) setDestination(destination, successCallbackopt, errorCallbackopt)

Set destination. This function sets the destination for logging.
Windows: If destination is set to sap.Logger.CONSOLE, logs are visible in Visual Studio's Output window only in Debug Type 'Mixed (Managed and Native)' mode.
Parameters:
Name Type Attributes Description
destination Array parameter [CONSOLE,FILESYSTEM]
successCallback function <optional>
Callback function called when the log level has been successfully set. No object will be passed to success callback.
errorCallback function <optional>
Callback function called when an error occurs while setting the log level. Since Kapsel Logger native code will always call the success callback function, the errorCallback function will be executed by Cordova if an error or exception occurs while making the call to the plugin.
Example
sap.Logger.setDestination([sap.Logger.CONSOLE], successCallback, errorCallback);

function successCallback() {
    alert("Destination set");
}

function errorCallback() {
    alert("Failed to set destination");
}

(static) setLogLevel(level, successCallbackopt, errorCallbackopt)

Set log level. This function sets the log level for logging.
Coverage of logging data in each log level: DEBUG < INFO < WARN < ERROR.
Following is the expected behavior to cover log messages at specific log levels:
ERROR : only ERROR messages
WARN : ERROR and WARN messages
INFO : ERROR, WARN and INFO
DEBUG : ERROR, WARN, INFO and DEBUG
For example, if you want to get all log messages, you need to set the log to the 'Debug' level. If the WARN level is set, logging data contains WARN and ERROR messages.
Default log level is ERROR.
Parameters:
Name Type Attributes Description
level String Log level to set [DEBUG, INFO, WARN, ERROR]
successCallback function <optional>
Callback function called when the log level has been successfully set. No object will be passed to success callback.
errorCallback function <optional>
Callback function called when an error occurs while setting the log level. Since Kapsel Logger native code will always call the success callback function, the errorCallback function will be executed by Cordova if an error or exception occurs while making the call to the plugin.
Example
sap.Logger.setLogLevel(sap.Logger.DEBUG, successCallback, errorCallback);

function successCallback() {
    alert("Log level set");
}

function errorCallback() {
    alert("Failed to set log level");
}

(static) upload(successCallback, errorCallback)

Upload a log file, with log entries, to SAP Mobile Platform server.
This function uploads a log file, which is helpful for collecting logging data from the app to trace bugs and issues. It uploads a log file, which contains log entries based on log level. Developers can access the log data in the Management Cockpit and/or a specific folder in installed server directly.

On iOS, the uploaded log messages are filtered by the log level at upon upload. For example, when you upload a log file with an ERROR log level, the uploaded log messages contain only ERROR log level messages. When you upload log files with an INFO level, uploaded log messages contain ERROR, WARN, and INFO log level messages.

On Android, generated log messages are filtered "at the log level." In other words, the already generated and filtered log messages at another log level are not affected by the current log level. Log messages are not filtered upon upload. For example, if you set the log level to DEBUG log messages are filtered at four levels (DEBUG, INFO, WARN, and ERROR. Logger on Android has four log levels messages. So, if you set the log level to WARN and upload a log file, the log file has four log level messages that were already generated at the DEBUG level.
Parameters:
Name Type Description
successCallback function Callback function called when a log file is successfully uploaded to the server. When a log file is successfully uploaded, it is fired. (with http statusCode and statusMessage for success)
errorCallback function Callback function called when an error occurs while uploading a log file to the server. If there is a connectivity error, such as an HTTP error, or unknown server error, it is fired with http statusCode and statusMessage for error.
Example
sap.Logger.upload(successCallback, errorCallback);

function successCallback() {
    alert("Upload Successful");
}

function errorCallback(e) {
    alert("Upload Failed. Status: " + e.statusCode + ", Message: " + e.statusMessage);
}

(static) warn(message, tagopt, successCallbackopt, errorCallbackopt)

Add a warning message to the log. This function logs messages with the 'WARN' log level.
Parameters:
Name Type Attributes Description
message String Log message to be logged.
tag String <optional>
Tag value added to the log entry used to indicate the source of the message (for example, SMP_LOGGER, SMP_AUTHPROXY).
successCallback function <optional>
Callback function called when the message has been successfully added to the log. No object will be passed to success callback.
errorCallback function <optional>
Callback function called when an error occurs while adding the message to the log. Since Kapsel Logger native code will always call the success callback function, the errorCallback function will be executed by Cordova if an error/exception occurs while making the call to the plugin.
Example
sap.Logger.warn("warn message", "WARN_TAG");