Using PmLogLib in QML

You can use the APIs described below to log information, including performance, in components or applications written using QML.

PmLogLib API

The PmLogLib API is provided as a QML plugin on PmLog of the qml-webos-components. After importing PmLog, you can use the methods defined below. The PmLogLib API supports singleton version as well as instance version.

Methods

Method	Description and Syntax
critical	Logs critical errors. Syntax: critical(msgid, kv_pairs, msg);
error	Logs errors. Syntax: error(msgid, kv_pairs, msg);
warning	Logs warning messages. Syntax: warning(msgid, kv_pairs, msg);
info	Logs usage metrics. Syntax: info(msgid, kv_pairs, msg);
debug	Logs debug messages. Syntax: debug(msg);

Parameters

The table below provides the description of the message elements. The msgid is mandatory, and kv_pairs and msg are optional.

Parameter Type Description

Parameter	Type	Description
msgid	string	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 QML 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. 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. Note 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	var (JSON object)	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. Note 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.
msg	string	The text to be logged.

msgid

string

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

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.

Note
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

var (JSON object)

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.

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

msg

string

The text to be logged.

Examples

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

Instance Version

import PmLog 1.0
PmLog {
     id: pmLog
     context: "com.webos.mycomponent"
}
pmLog.error("APPCRASH", {"APP_NAME":  "Facebook", "APP_ID": appId}, "Facebook app crashed, restart application");
pmLog.info("URLLOAD", {"URL": "http://webosose.org", "TIME": 200, "UNIT": "ms"});
pmLog.debug("BRWSRCLOSE");

Output:

1970-01-01T00:01:05.714335Z [65] user.error DBGFRWK[1550]: com.webos.mycomponent APPCRASH {"APP_ID": "com.webos.app.facebook", "APP_NAME": "Facebook"} Facebook app crashed, restart application
1970-01-01T00:01:05.714572Z [65] user.info DBGFRWK[1550]: com.webos.mycomponent URLLOAD {"TIME": 200, "UNIT": "ms", "URL": "http://webosose.org"}
1970-01-01T00:01:05.714667Z [65] user.debug DBGFRWK[1550]: com.webos.mycomponent BRWSRCLOSE

Singleton Version

import PmLog 1.0
PmLogger.context = "qml";

PmLogger.error("APPCRASH", {"APP_NAME": "Facebook", "APP_ID": appId}, "Facebook app crashed, restart application");
PmLogger.info("URLLOAD", {"URL": "http://webosose.org", "TIME": 200, "UNIT": "ms"});
PmLogger.debug("BRWSRCLOSE");

Output:

1970-01-01T00:01:05.713362Z [65] user.error DBGFRWK[1550]: qml APPCRASH {"APP_ID": "com.webos.app.facebook", "APP_NAME": "Facebook"} Facebook app crashed, restart application
1970-01-01T00:01:05.713800Z [65] user.info DBGFRWK[1550]: qml URLLOAD {"TIME": 200, "UNIT": "ms", "URL": "http://webosose.org"}
1970-01-01T00:01:05.713971Z [65] user.debug DBGFRWK[1550]: qml BRWSRCLOSE

PmLogLib Performance API

The PmLogLib performance API is provided as a QML plugin on PerformanceLog of the qml-webos-components. After importing PerformanceLog, you can use the methods defined below. The PmLogLib performance API supports singleton version as well as instance version.

Methods

These methods can be used to measure performance time. They can measure time across processes. Both time and timeEnd log the time (in milliseconds) that was spent between the calls. Both take msgid and kv_pairs parameters that identify the measurement point. The kv_pairs and msg parameters are optional.

For parameter description, see Parameters.

Method	Description and Syntax
time	Starts a new timer. Syntax: time(msgid, kv_pairs);
timeEnd	Stops a timer and prints the elapsed time. Syntax: timeEnd(msgid, kv_pairs, msg);

time

Starts a new timer.

Syntax:

time(msgid, kv_pairs);

timeEnd

Stops a timer and prints the elapsed time.

Syntax:

timeEnd(msgid, kv_pairs, msg);

Examples

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

Instance Version

import PerformanceLog 1.0
PerformanceLog {
     id: perfLog
     context: "com.webos.mycomponent"
}
perfLog.time("APP_LAUNCH", {"APP_ID": appId});
perfLog.timeEnd("APP_LAUNCH", {"APP_ID": appId}, "Web application is launched from Showcase");
perfLog.time("APP_SWITCH", {"APP_FROM": "Angry Birds", "APP_TO": "Chess"});
perfLog.timeEnd("APP_SWITCH", {"APP_FROM": "Angry Birds", "APP_TO": "Chess"});
perfLog.time("BROWSER_LOAD");
perfLog.timeEnd("BROWSER_LOAD");

Output:

1970-01-01T00:01:09.303503Z [69] 192 local0.info DBGFRWK[1552]: com.webos.mycomponent APP_LAUNCH {"APP_ID": "com.webos.app.facebook", "UNIT": "ms", "TIME": 2} Web application is launched from Showcase
1970-01-01T00:01:09.304773Z [69] 192 local0.info DBGFRWK[1552]: com.webos.mycomponent APP_SWITCH {"APP_FROM": "Angry Birds", "APP_TO": "Chess", "UNIT": "ms", "TIME": 1}
1970-01-01T00:01:09.305467Z [69] 192 local0.info DBGFRWK[1552]: com.webos.mycomponent BROWSER_LOAD {"UNIT": "ms", "TIME": 1}

Singleton Version

import PerformanceLog1.0
PerformanceLogger.context = "qmlPerformance";

PerformanceLogger.time("APP_LAUNCH", {"APP_ID": appId});
PerformanceLogger.timeEnd("APP_LAUNCH", {"APP_ID": appId}, "Web application launched from Showcase");
PerformanceLogger.time("APP_SWITCH", {"APP_FROM": "Angry Birds", "APP_TO": "Chess"});
PerformanceLogger.timeEnd("APP_SWITCH", {"APP_FROM": "Angry Birds", "APP_TO": "Chess"});
PerformanceLogger.time("BROWSER_LOAD");
PerformanceLogger.timeEnd("BROWSER_LOAD");

Output:

1970-01-01T00:01:09.303503Z [69] 192 local0.info DBGFRWK[1552]: qmlPerformance APP_LAUNCH {"APP_ID": "com.webos.app.facebook", "UNIT": "ms", "TIME": 2} Web application is launched from Showcase
1970-01-01T00:01:09.304773Z [69] 192 local0.info DBGFRWK[1552]: qmlPerformance APP_SWITCH {"APP_FROM": "Angry Birds", "APP_TO": "Chess", "UNIT": "ms", "TIME": 1}
1970-01-01T00:01:09.305467Z [69] 192 local0.info DBGFRWK[1552]: qmlPerformance BROWSER_LOAD {"UNIT": "ms", "TIME": 1}