Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

Log

Methods 9  
Properties 11
Examples 5

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 "::" instead of ".")
String: file

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

Constant: Rho.Log.DEST_OUTPUT (For Ruby use "::" instead of ".")
String: stdio

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

Constant: Rho.Log.DEST_URI (For Ruby use "::" instead of ".")
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 "::" instead of ".")
String: 0

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

Constant: Rho.Log.LEVEL_INFO (For Ruby use "::" instead of ".")
String: 1

Information level logs and above will be shown.

Constant: Rho.Log.LEVEL_WARNING (For Ruby use "::" instead of ".")
String: 2

Warnings and above will only be shown.

Constant: Rho.Log.LEVEL_ERROR (For Ruby use "::" instead of ".")
String: 3

Error level log messages and above will be shown.

Constant: Rho.Log.LEVEL_FATAL (For Ruby use "::" instead of ".")
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 local http server traces. 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 remote server app (and / or shared runtime). Default value can be overridden by the setting in rhoconfig.txt (net_trace)

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