Using PmLog in JavaScript

You can use the APIs described below to log information in web applications written using JavaScript that run on the device (developed in Enact or using any other web application framework).

APIs for Web Applications

The pmloglib API is provided as a webOS-specific Cordova (a.k.a. PhoneGap) plugin on the "window.webOS" namespace.  Any web application that includes Cordova for webOS (e.g. cordova.webos.js) will be able to call pmloglib APIs.

PmLogLib API

API Description and Syntax

webOS.critical

Logs critical errors.

Syntax:

webOS.critical(msgid, kv_pairs, msg)

webOS.error

Logs errors.

Syntax:

webOS.error(msgid, kv_pairs, msg)

webOS.warning

Logs warning messages.

Syntax:

webOS.warning(msgid, kv_pairs, msg)

webOS.info

Logs usage metrics.

Syntax:

webOS.info(msgid, kv_pairs, msg)

webOS.debug

Logs debug messages.

Syntax:

webOS.debug(msg)

Parameters

The table below provides the description of the message components.

Parameter Type Description

msgid

const char *

The msgid is an arbitrary short string (in most cases between 5 and 16 characters long) that uniquely identifies a log message within a component. The msgid cannot be a NULL or an empty string. It cannot contain a blank space (" ") or curly brackets ("{}") in it. 

Every log statement, except for the debug and trace log statement, is expected to have a unique msgid to clearly differentiate the messages by function and use them for metrics analysis. For example, the number of native app launches per session, can be determined by counting the messages with msgid. The selection of the message IDs is left up to the developer. Typically it would be a short string in all capitals, for example, APPSTRT. It is not necessary that the meaning of the message is apparent from the msgid alone, but it is best to standardize on the names.

The msgids must be defined in a separate header file with comments to indicate their purpose. This will be used in data crunching for metrics. For example: 

#define MSGID_APP_START “APPSTRT” /** App started successfully */

It may be an additional burden on the developers to add message IDs to log statements. However, considering that our logs at or above INFO should only include significant information, we expect that programs will not need a large number of message IDs and the effort required will be kept minimal. 

The msgid is not required if the level parameter is set to debug. Since debug level logs are used by developers for code debugging and not used for metrics analysis, it is kept simpler for developers to log as a free-text at the debug level.

kv_pairs

const char *

This is an optional parameter which consists of a set of key-value pairs followed by a free text to provide additional information in the logs which can be used for analytics purpose.

This parameter is optional, as long as the message ID itself is descriptive. For example, a message with an ID of NETWORK_DOWN or READ_CONF_FAIL is self-descriptive and does not need additional information passed as a parameter.

  • Info and the higher level of messages should use key-value pairs to provide useful information about the log.

  • Keys should NOT contain a colon (":") in it.

  • A key-value pair must be built using the following helper macros:

    • PMLOGKFV(literal_key, literal_fmt, value) – is a macro which helps build a key-value pair, based on the literal_fmt. 

    • PMLOGKS(literal_key, string_value) – is a macro which helps build a key-value pair for string literals.

    • PMLOGJSON(literal_key, json_object_string) - is a macro which helps build a key-value pair for stringified JSON object.

    To log a boolean message, use PMLOGKFV("BOOLKEY","%s","true").

    If double quotes are to be used in a value string, it should be stringified. For example:

    PMLOGKS("KEY", g_strescape("my \"quoted\" string value"));

  • A free text - is the message part of the log. Since this is a format string, it can contain format specifiers, such as %d or %s. These format specifiers will be replaced with respective parameters in the variable parameter list. If a message does not have a free text to log, then it is specified as a blank space (" "). This text is to benefit from a human reading the logs. It will be discarded for any metrics gathering. Hence you must not use this field alone to log critical information. Here is an example of a free text: 

    PmLogMsg (my_context, Info, "APPLAUNCH", 3, PMLOGKFV("ID", "%d", app_info->id), PMLOGKS("NAME", app_info->name), PMLOGKS("STATUS", "launched"), "App launched successfully in %s", _func_);

msg

const char *

The text to be logged.

Example

The following is the sample code for how components written in JavaScript can log information.

webOS.error("APPCRASH", {"APP_NAME": "Facebook", "APP_ID": appId}, "Facebook app crashed, restart application");
Except as noted, this content is licensed under Creative Commons Attribution 4.0 and sample code is licensed under Apache License 2.0.