Overview
Use this API to control the behavior of the log as well as access it. This API gives access to the Logging functionality. There are five functions to add messages to the log with different severity (from lowest to highest) : trace, info, warning, error and fatal. Each of those functions gets two parameters: message and category. Category is an user defined group that helps with used searching and filtering.
Accessing Log File: sendLogFile: will sent all the log to server showLog: brings up popup with log, readLogFile: returns the full log file, cleanLogFile: removes all logged messages
Filtering:
Using level property: It limits minimal severity of messages that will be added to log. For example: setting log level to 2 (warning) will filter out messages generated by trace and info.
Categories: user defined groups that are used to select messages from different modules for ease of use. There are two main filters: includeCategories and excludeCategories. They are both active at the same time. includeCategories allows to select groups/categories that should be in the log (setting this property to empty will turn disable logging). excludeCategories is used for filtering out some of categories.
excludeFilter, this filter is used to remove all sensitive information like passwords, security tokens from log.
Log destinations (any combinations of them):
- debug console (stdio),
- device filesystem (file)
- remote sever (url)
Enabling the API
There are two methods of enabling the Log API:
- Include all ebapi modules
- Include only the required API modules
For either of these methods, you'll need to include files from the /Enterprise Browser/JavaScript Files/Enterprise Browser directory on the computer that you installed the Enterprise Browser.
Include all JS API modules
To include all JS APIs, copy the ebapi-modules.js file to a location accessible by the app's files and include a reference to the JavaScript file in the app's HTML. For instance, to include the modules file in the app's index.html, copy the file to the same directory as that index.html and add the following line to the HTML's HEAD section:
<script type="text/javascript" charset="utf-8" src="ebapi-modules.js"></script>
Note: that the pathing for this file is relative to the current page.
This will define the EB class within the page. Any page you need to use the modules will need to have the .js file included in this fashion.
Include only the required modules
To include single APIs, you must first include the ebapi.js in your HTML as well as the API file you want to use. For instance, to use the Log API, I would add the following code to my HTML file(s), assuming the API files have been copied to the same directory as the HTML.
<script type="text/javascript" charset="utf-8" src="ebapi.js"></script>
<script type="text/javascript" charset="utf-8" src="eb.log.js"></script>
The ebapi.js file is necessary for all single API inclusions.
Methods
cleanLogFile()
Clean log file, all logged messages will be removed.
Parameters
- callback : CallBackHandler
Returns
Synchronous Return:
- Void
Platforms
- Android
- Windows Mobile
- Windows CE
Method Access:
- Class Method: This method can only be accessed via the API class object.
EB.Log.cleanLogFile()
error(STRING message, STRING category)
Log message at the Error level.
Parameters
- message : STRING
Log message.
- category : STRING Default: APP
Log category.
- callback : CallBackHandler
Returns
Synchronous Return:
- Void
Platforms
- Android
- Windows Mobile
- Windows CE
Method Access:
- Class Method: This method can only be accessed via the API class object.
EB.Log.error(STRING message, STRING category)
fatalError(STRING message, STRING category)
Log message at the FatalError level. Application will be terminated.
Parameters
- message : STRING
Log message.
- category : STRING Default: APP
Log category.
- callback : CallBackHandler
Returns
Synchronous Return:
- Void
Platforms
- Android
- Windows Mobile
- Windows CE
Method Access:
- Class Method: This method can only be accessed via the API class object.
EB.Log.fatalError(STRING message, STRING category)
info(STRING message, STRING category)
Log message at the Info level.
Parameters
- message : STRING
Log message.
- category : STRING Default: APP
Log category.
- callback : CallBackHandler
Returns
Synchronous Return:
- Void
Platforms
- Android
- Windows Mobile
- Windows CE
Method Access:
- Class Method: This method can only be accessed via the API class object.
EB.Log.info(STRING message, STRING category)
readLogFile(INTEGER limit)
Read log file. Returns string from the log file containing specified number of symbols.
Parameters
- limit : INTEGER
Maximum size of the resulting string in symbols.
- callback : CallBackHandler
Callback
Async Callback Returning Parameters: STRING
Returns
Synchronous Return:
- STRING
Platforms
- Android
- Windows Mobile
- Windows CE
Method Access:
- Class Method: This method can only be accessed via the API class object.
EB.Log.readLogFile(INTEGER limit)
sendLogFile()
Send log file to destinationURI property. Please note that this procedure is blocking and will stop any logging while log file is being send.
Parameters
- callback : CallBackHandler
Returns
Synchronous Return:
- Void
Platforms
- Android
- Windows Mobile
- Windows CE
Method Access:
- Class Method: This method can only be accessed via the API class object.
EB.Log.sendLogFile()
showLog()
Display Log view window.
Parameters
- callback : CallBackHandler
Returns
Synchronous Return:
- Void
Platforms
- Android
- Windows Mobile
- Windows CE
Method Access:
- Class Method: This method can only be accessed via the API class object.
EB.Log.showLog()
trace(STRING message, STRING category)
Log message at the Trace level. By default trace messages are not shown in log (if level equals to 1).
Parameters
- message : STRING
Log message.
- category : STRING Default: APP
Log category.
- callback : CallBackHandler
Returns
Synchronous Return:
- Void
Platforms
- Android
- Windows Mobile
- Windows CE
Method Access:
- Class Method: This method can only be accessed via the API class object.
EB.Log.trace(STRING message, STRING category)
warning(STRING message, STRING category)
Log message at the Warning level.
Parameters
- message : STRING
Log message.
- category : STRING Default: APP
Log category.
- callback : CallBackHandler
Returns
Synchronous Return:
- Void
Platforms
- Android
- Windows Mobile
- Windows CE
Method Access:
- Class Method: This method can only be accessed via the API class object.
EB.Log.warning(STRING message, STRING category)
Properties
destination
Type
ARRAY
Description
List of log destinations that are being used. Destination could be set to empty (disable all logging), Logging to several destinations could be set by setting destination to comma separated list in any order (for example "stdio,file"). By default logging to console can be enabled from Config.xml).
Values
Possible Values (STRING):
- Constant: EB.Log.DEST_FILE - String: file Log is written to a local file on the device (typically Log.txt)
- Constant: EB.Log.DEST_OUTPUT - String: stdio Log is written to the standard output (ex: Android ADB)
- Constant: EB.Log.DEST_URI - String: uri Log is written to a remote logger.
Access
- Class: This property can only be accessed via the API class object.
EB.Log.destination
Platforms
- Android
- Windows Mobile
- Windows CE
destinationURI
Type
STRING
Description
Log server URI where log will be posted by using EB.Log.sendLogFile or from the log view. Log server source code is open and available at http://github.com/rhomobile/rhologs, so you can deploy your own logserver. URI format: 'http://host:port[/path][?log_name=appName]'. Default value is set in Config.xml in the LogURI setting under the Logger section.
Access
- Class: This property can only be accessed via the API class object.
EB.Log.destinationURI
Platforms
- Android
- Windows Mobile
- Windows CE
excludeCategories
Type
STRING
Description
Comma-separated list of excluded log categories. Set to '' (empty) to allow all messages to be logged. Set to concrete value to filter out log from those categories. Default value is '' (empty), it is set in Config.xml
Access
- Class: This property can only be accessed via the API class object.
EB.Log.excludeCategories
Platforms
- Android
- Windows Mobile
- Windows CE
excludeFilter
Type
STRING
Description
Define exclude parameters log filter(for security reasons) - parameter names separated by comma. It works when user tries to put in log string containing json / urls. Default value is "" (empty). For example, if user set excludeFilter="password", then tries to put in log this string: "{"user":"alex","password":"abcdef","sessionid":123456}", "abcdef" will not appear in log.
Access
- Class: This property can only be accessed via the API class object.
EB.Log.excludeFilter
Platforms
- Android
- Windows Mobile
- Windows CE
filePath
Type
STRING
Description
Path to the log file including file name. The path is relative to the platform specific application root or start if from '/' if you wish to store elsewhere ('/mnt/sdcard/myapp.log'). Default file path is Log.txt
Access
- Class: This property can only be accessed via the API class object.
EB.Log.filePath
Platforms
- Android
- Windows Mobile
- Windows CE
fileSize
Type
INTEGER
Description
Maximum log file size in bytes, set 0 to unlimited size; when limit is reached, log wraps to beginning of file. Default value is 50000, it is set in Config.xml
Params
Default: 50000
Access
- Class: This property can only be accessed via the API class object.
EB.Log.fileSize
Platforms
- Android
- Windows Mobile
- Windows CE
includeCategories
Type
STRING
Description
Comma-separated list of included log categories. Set to '*' (asterisk) to log all categories. Set to '' (empty) to filter out all messages. Default value is '*' (asterisk), it is set in Config.xml.
Params
Default: *
Access
- Class: This property can only be accessed via the API class object.
EB.Log.includeCategories
Platforms
- Android
- Windows Mobile
- Windows CE
level
Type
INTEGER
Description
The current logging level. Minimal severity level of messages that will appear in log. When level is set to 0 any messages will be logged. When level is set to 4 only fatal error messages will be logged. Default value is defined in Config.xml
Values
Possible Values (STRING):
- Constant: EB.Log.LEVEL_TRACE - String: 0 Everything will be logged. Also see settings for controlling log size.
- Constant: EB.Log.LEVEL_INFO - String: 1 Information level logs and above will be shown.
- Constant: EB.Log.LEVEL_WARNING - String: 2 Warnings and above will only be shown.
- Constant: EB.Log.LEVEL_ERROR - String: 3 Error level log messages and above will be shown.
- Constant: EB.Log.LEVEL_FATAL - String: 4 Fatal level log messages and above will be shown.
Access
- Class: This property can only be accessed via the API class object.
EB.Log.level
Platforms
- Android
- Windows Mobile
- Windows CE
memoryPeriod
Type
INTEGER
Description
Enables the logging of memory usage in the system; specifies the time interval in milliseconds at which memory logs will be generated periodically. Setting it to 0 will disable logging memory information.
Params
Default: 0
Access
- Class: This property can only be accessed via the API class object.
EB.Log.memoryPeriod
Platforms
- Android
- Windows Mobile
- Windows CE
netTrace
Type
BOOLEAN
Description
Turn on remote network traces regardless of log level set (e.g. Network, asyncHttp). Traces contain information about connection process, sent and received headers and data. Please note that this parameter will not take an effect in case of local server app. Default value can be overridden by the setting in Config.xml. To get local server trace, use Rho.Log.LEVEL_TRACE.
Params
Default: false
Access
- Class: This property can only be accessed via the API class object.
EB.Log.netTrace
Platforms
- Android
skipPost
Type
BOOLEAN
Description
Skip http package body from log(for security reasons). Please note that this parameter will not take an effect in case of remote server app (and / or shared runtime), no log will appear in this case.
Params
Default: false
Access
- Class: This property can only be accessed via the API class object.
EB.Log.skipPost
Platforms
- Android
- Windows Mobile
- Windows CE