Server preparation for uploaded log data

Prepare the server to receive uploaded client log data.

Upon receiving uploaded client logs, the MobileFirst production server passes the uploaded data to the Operational Analytics component feature and to an adapter that you create and deploy. Neither of these options are present in a production MobileFirst Server; install and configure them. To receive and persist uploaded client logs at the MobileFirst Server, we must take at least one of the following two actions:

1. Install operational analytics as described in Install operational analytics.

2. Deploy an adapter named WLClientLogReceiver or the name that corresponds to the value of the wl.clientlogs.adapter.name JNDI property.

If we deploy an adapter to receive uploaded client logs, the adapter must be an HTTP adapter named WLClientLogReceiver or the value of the wl.clientlogs.adapter.name JNDI property. The adapter must have at least one procedure that must be named log. The log procedure is passed two parameters: deviceInfo (a JSON object) and logMessages (a JSON array). For more information about implementing adapter procedures, see Implementing adapter procedures.

The following example shows an implementation of the log procedure in the WLClientLogReceiver-impl.js file:

function log(deviceInfo, logMessages) {
  /* The adapter can choose to process the parameters, 
     for example to forward them to a backend server for 
     safekeeping and further analysis.
     The deviceInfo object may look like this:
     {
       "appName":       "wlapp",    "appVersion":    "1.0",    "deviceId":      "66eed0c9-ecf7-355f-914a-3cedac70ebcc",    "model":         "Galaxy Nexus - 4.2.2 - API 17 - 720x1280",    "systemName":    "Android",    "systemVersion": "4.2.2",    "os.arch":       "i686",       // Android only        "os.version":    "3.4.0-qemu+"     // Android only       The logMessages parameter is a JSON array 
      containing JSON object elements, and might look like this:
        [{
          "timestamp"    : "17-02-2013 13:54:23:745",  // "dd-MM-yyyy hh:mm:ss:S"
          "level"        : "ERROR",                // ERROR || WARN || INFO || LOG || DEBUG
          "package"      : "your_tag",             // typically a class name, app name, or JavaScript object name           "msg"          : "the message",          // a helpful log message
          "threadid"     : 42,                     // (Android only) id of the current thread
          "metadata"     : { "$src" : "js" }           // additional metadata placed on the log call
        }]
  */
  return true;
}

The procedure element in the WLClientLogReceiver.xml file for log:

<procedure name="log" />

The implementation of the adapter determines the destination of the uploaded log content.

One convenient way to persistently record uploaded client logs is to place the audit="true" attribute in the adapter's procedure element. This flag instructs the MobileFirst Server to report all adapter invocations and parameter arguments inline to the server log file:

<procedure name="log" audit="true" />

Alternatively, you process the parameters that are passed into the log procedure explicitly.

Server security

By default, the servlet that receives uploaded client logs at the MobileFirst Server is configured in authenticationConfig.xml.with a security test that includes application authenticity check. We can change the security tests that protect the servlet. But to avoid unexpectedly prompting the user for authentication credentials when you send logs, two choices:

1. Use a security test that requires no custom challenge handler code and no user interaction, and freely call the logger send function.

2. Ensure that the security test in front of the servlet remains the same as the security test of the application, and be careful about placement of extra logger send function calls.

If we choose to change the security test, and you choose option one, an explicit call to the logger send function does not result in an unexpected authentication challenge prompt or other authentication failure. The logger send function is safe to place throughout the application.

If we choose to change the security test, and you choose option two, a carelessly placed call to the logger send function might result in an unexpected authentication challenge prompt or other authentication failure. In this case, explicit calls to the logger send function in the application must be placed carefully. If the client applications call the logger send function explicitly, ensure that they do so after authentication succeeds. For example, call the logger send function in the invokeProcedure onSuccess callback of an adapter invocation that is protected by the same security test as the log receiver servlet.

Logging sensitive data

The logger library does not automatically protect against logging sensitive data. Data is stored in plain text, but is only readable within the context of the application that is using the logger API. Avoid logging sensitive data

Uploaded client logs

In the embedded Liberty development server, the uploaded client logs are written to a file that corresponds with that client's unique attributes. The uploaded client log file is written, or appended, at the following path, which is a peer to the logs folder:

clientlogs/[os]/[os_version]/[app_id]/[app_version]/[device_id].log

Uploaded logs are not written to the file system in MobileFirst production servers.

Parent topic: Client-side log capture