Log
Use this API to control the behavior of the RhoMobile Log API 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
This API is part of the coreapi extension that is included automatically.
extensions: ["coreapi"]
JavaScript Usage
Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript
Ruby Usage
Be sure to review the Ruby API Usage guide for important information about using this API in Ruby
Methods
Clean log file, all logged messages will be removed.
Synchronous Return:
- Void
Method Access:
-
Class Method: This method can only be accessed via the API class object.
- JavaScript:
Rho.Log.cleanLogFile() - Ruby:
Rho::Log.cleanLogFile()
- JavaScript:
Log message at the Error level.
Parameters
- message : STRING
Log message.
- category : STRING Default: APP
Log category.
Synchronous Return:
- Void
Method Access:
-
Class Method: This method can only be accessed via the API class object.
- JavaScript:
Rho.Log.error(STRING message, STRING category) - Ruby:
Rho::Log.error(STRING message, STRING category)
- JavaScript:
Log message at the FatalError level. Application will be terminated (on all platforms except iOS).
Parameters
- message : STRING
Log message.
- category : STRING Default: APP
Log category.
Synchronous Return:
- Void
Method Access:
-
Class Method: This method can only be accessed via the API class object.
- JavaScript:
Rho.Log.fatalError(STRING message, STRING category) - Ruby:
Rho::Log.fatalError(STRING message, STRING category)
- JavaScript:
Log message at the Info level.
Parameters
- message : STRING
Log message.
- category : STRING Default: APP
Log category.
Synchronous Return:
- Void
Method Access:
-
Class Method: This method can only be accessed via the API class object.
- JavaScript:
Rho.Log.info(STRING message, STRING category) - Ruby:
Rho::Log.info(STRING message, STRING category)
- JavaScript:
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.
Synchronous Return:
- STRING
Method Access:
-
Class Method: This method can only be accessed via the API class object.
- JavaScript:
Rho.Log.readLogFile(INTEGER limit) - Ruby:
Rho::Log.readLogFile(INTEGER limit)
- JavaScript:
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 Optional
Synchronous Return:
- Void : this method also supports async callbacks - check the Callback tab for callback return parameters.
Method Access:
-
Class Method: This method can only be accessed via the API class object.
- JavaScript:
Rho.Log.sendLogFile(CallBackHandler callback) - Ruby:
Rho::Log.sendLogFile(CallBackHandler callback)
- JavaScript:
Display Log view window.
Synchronous Return:
- Void
Method Access:
-
Class Method: This method can only be accessed via the API class object.
- JavaScript:
Rho.Log.showLog() - Ruby:
Rho::Log.showLog()
- JavaScript:
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.
Synchronous Return:
- Void
Method Access:
-
Class Method: This method can only be accessed via the API class object.
- JavaScript:
Rho.Log.trace(STRING message, STRING category) - Ruby:
Rho::Log.trace(STRING message, STRING category)
- JavaScript:
Log message at the Warning level.
Parameters
- message : STRING
Log message.
- category : STRING Default: APP
Log category.
Synchronous Return:
- Void
Method Access:
-
Class Method: This method can only be accessed via the API class object.
- JavaScript:
Rho.Log.warning(STRING message, STRING category) - Ruby:
Rho::Log.warning(STRING message, STRING category)
- JavaScript:
Properties
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 rhoconfig.txt (LogToOutput = 1). After Rhodes initialization logging to file is enabled automatically.
Possible Values (STRING):
String: file
Log is written to a local file on the device (typically rholog.txt)
String: stdio
Log is written to the standard output (ex: Android ADB)
String: uri
Log is written to a remote logger.
Property Access:
-
Instance: This property can be accessed via an instance object of this class:
myObject.destination
Log server URI where log will be posted by using Rho::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 rhoconfig.txt (logserver)
Property Access:
-
Instance: This property can be accessed via an instance object of this class:
myObject.destinationURI
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 rhoconfig.txt (ExcludeLogCategories)
Property Access:
-
Instance: This property can be accessed via an instance object of this class:
myObject.excludeCategories
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.
Property Access:
-
Instance: This property can be accessed via an instance object of this class:
myObject.excludeFilter
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 “rholog.txt”
Default: rholog.txt
Property Access:
-
Instance: This property can be accessed via an instance object of this class:
myObject.filePath
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 rhoconfig.txt (MaxLogFileSize)
Default: 50000
Property Access:
-
Instance: This property can be accessed via an instance object of this class:
myObject.fileSize
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 rhoconfig.txt (LogCategories).
Default: *
Property Access:
-
Instance: This property can be accessed via an instance object of this class:
myObject.includeCategories
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 rhoconfig.txt (MinSeverity)
Possible Values (STRING):
String: 0
Everything will be logged. Also see settings for controlling log size.
String: 1
Information level logs and above will be shown.
String: 2
Warnings and above will only be shown.
String: 3
Error level log messages and above will be shown.
String: 4
Fatal level log messages and above will be shown.
Property Access:
-
Instance: This property can be accessed via an instance object of this class:
myObject.level
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.
Default: 0
Property Access:
-
Instance: This property can be accessed via an instance object of this class:
myObject.memoryPeriod
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 (and / or shared runtime). Default value can be overridden by the setting in rhoconfig.txt (net_trace). To get local server trace, use Rho.Log.LEVEL_TRACE in JavaScript and Rho::Log::LEVEL_TRACE in Ruby.
Default: false
Property Access:
-
Instance: This property can be accessed via an instance object of this class:
myObject.netTrace
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.
Default: false
Property Access:
-
Instance: This property can be accessed via an instance object of this class:
myObject.skipPost
Examples
Show the contents of the log file in a window with controls to refresh, clear and send. Useful for debugging and when asking users to report error messages.
Rho.Log.showLog();
Rho::Log.showLog
Retrieve the contents of the log file as a string.
//Read at most 16384 symbols logFileContent = Rho.Log.readLogFile(16384);
# Read at most 16384 symbols logFileContent = Rho::Log.readLogFile 16384
Clear the contents of the log file. In this example, logFileContentBefore will contain the log up until that point, while logFileContentAfter will be empty.
// Read log file logFileContentBefore = Rho.Log.readLogFile(16384); // Clear log file Rho.Log.cleanLogFile(); // Read log file again - this time it will be empty logFileContentAfter = Rho.Log.readLogFile(16384);
# Read log file logFileContentBefore = Rho::Log.readLogFile 16384 # Clear log file Rho::Log.cleanLogFile # Read log file again - this time it will be empty logFileContentAfter = Rho::Log.readLogFile(16384
Categories help you organize your logging messages and find related statements using tools like grep or a text editor’s “search” function.
Rho.Log.info("Consectetuer adipiscing elit", "Lorem Ipsum"); Rho.Log.info("Foo acquired value Bar in method Baz", "Miscellaneous"); //The above code will result in logging statements like these Lorem Ipsum| Consectetuer adipiscing elit Miscellaneous Foo acquired value Bar in method Baz
Rho::Log.info("Consectetuer adipiscing elit", "Lorem Ipsum") Rho::Log.info("Foo acquired value Bar in method Baz", "Miscellaneous") #The above code will result in logging statements like these Lorem Ipsum| Consectetuer adipiscing elit Miscellaneous Foo acquired value Bar in method Baz
You can ask the system to automatically log memory usage information on a set interval. This can be used to debug potential memory leaks in operations where a high number of objects are touched in memory.
Rho.Log.memoryPeriod = 1000; // Perform memory-intensive operations here. Examining the log will tell us if we have a memory leak // Once our task finishes, disable automatic memory logging Rho.Log.memoryPeriod = 0;
# Request that memory usage be logged automatically by the system every second. Rho::Log.memoryPeriod = 1000 # Perform memory-intensive operations here. Examining the log will tell us if we have a memory leak # Once our task finishes, disable automatic memory logging Rho::Log.memoryPeriod = 0