Warning Unreleased Docs! - You may be viewing documentation that reflects an upcoming release and the functionality described may not be in the current version you are using. Change the version above to the most recent version.

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

cleanLogFile
()

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()
error
(STRING message, STRING category)

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)
fatalError
(STRING message, STRING category)

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)
info
(STRING message, STRING category)

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)
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.

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)
sendLogFile
(CallBackHandler callback)

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)
showLog
()

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()
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.

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)
warning
(STRING message, STRING category)

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)

Properties

destination
: ARRAY

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):

Constant: Rho.Log.DEST_FILE (For Ruby use "::" for all "." when referencing constants)
String: file

Log is written to a local file on the device (typically rholog.txt)

Constant: Rho.Log.DEST_OUTPUT (For Ruby use "::" for all "." when referencing constants)
String: stdio

Log is written to the standard output (ex: Android ADB)

Constant: Rho.Log.DEST_URI (For Ruby use "::" for all "." when referencing constants)
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
destinationURI
: STRING

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
excludeCategories
: STRING

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
excludeFilter
: STRING

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
filePath
: STRING

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
fileSize
: INTEGER

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
includeCategories
: STRING

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
level
: INTEGER

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):

Constant: Rho.Log.LEVEL_TRACE (For Ruby use "::" for all "." when referencing constants)
String: 0

Everything will be logged. Also see settings for controlling log size.

Constant: Rho.Log.LEVEL_INFO (For Ruby use "::" for all "." when referencing constants)
String: 1

Information level logs and above will be shown.

Constant: Rho.Log.LEVEL_WARNING (For Ruby use "::" for all "." when referencing constants)
String: 2

Warnings and above will only be shown.

Constant: Rho.Log.LEVEL_ERROR (For Ruby use "::" for all "." when referencing constants)
String: 3

Error level log messages and above will be shown.

Constant: Rho.Log.LEVEL_FATAL (For Ruby use "::" for all "." when referencing constants)
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
memoryPeriod
: INTEGER

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
netTrace
: BOOLEAN

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
skipPost
: BOOLEAN

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 log file

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
                
Read log file content

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
                
Clean log file

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
                
Logging categories

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

                
Memory Usage

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