Log

Enterprise Browser 3.0

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