IAM JSON formats

Introduction

The In-App Monitoring Library (IAM) collects performance measurements in the App. These measurements are forwarded to an Acceptor either directly after the measurement is complete, or in batches at a later time. This behavior depends on the configuration on the IAM library and the current state of the network (e.g. connectivity yes/no, roaming yes/no, wifi yes/no). The end-point (URL) of the Acceptor will be specified by the developer of the App, and can be a server of the owner of the App or a third party like WatchMouse.

The measurements wil be dispatched to the Acceptor using a HTTP POST operation. The measurments are sent as a JSON array (see Measurement Data section below), which is placed in the body of the POST request. The content-type of the body shall be application/jsonrequest. 
The result of the POST operation is a JSON object, specified below (section Acceptor Response).

Measurement Data

The measurements are dispatched to the Acceptor in a JSON object with the following key/value pairs. These are obligatory unless specified otherwise.
  • app: a string, the application name
  • appversion: a string with the version of the application (optional)
  • key: a string containing the developer key (optional)
  • batched: true when this is a batch of measurements, collected earlier. false if measurement data immediately after it was completed.
  • measurements: an JSON array of measurements objects (see below)
  • device: the name of the device (optional)
  • model: the device model (optional)
  • os_version: the name and version of the operating system (optional)
  • hash: a hash over all key/values [TBD]
The measurement objects have the following set of obligatory key/value pairs. These are obligatory unless specified otherwise.
  • result: number representing what error occurred. If no error occurred, this will have value 0
  • error: human readable string with English error message (optional, and HTML encoded if present) 
  • when: time and date in UTC formated according to ISO8601 when the measurement started.
  • url: the URL, the endpoint of the HTTP call (e.g. REST call or web page, string HTML encoded)
  • c_type: the connection type cellular network or wwan (possible values: wwan OR wifi OR null) 
  • mcc: the Mobile Country Code (string) at the time of the measurement (optional)
  • mnc: the Mobile Network Code  (string) at the time of the measurement (optional)
  • ipaddr: the IPv4 or IPv6 address (string) of the device at the time of the measurement (optional)
  • country: country code, lowercase ISO string (optional)
  • lat: latitude, (number, decimal degrees) at the time of the measurement (optional)
  • lon: longitude, (number, decimal degrees) at the time of the measurement (optional)
  • cell_id:  cell tower id (optional)
  • lac: location area code (optional)
  • t_connect: time from start of call to TCP connect, in milliseconds (optional)
  • t_firstbyte: time from TCP connect to first byte received, in milliseconds (optional)
  • t_done: time from TCP connect to last byte received, in milliseconds (optional)
  • size: number of bytes received (optional)
Can't necessarily log the t_connect, t_firstbyte and t_done and size in all cases so optional, but will in most cases be present. 

Depending on the configuration settings of IAM library, a combination of location specific key/value pairs can be logged and dispatched, e.g 
  • mcc, mnc: when available and allowed to capture
  • ipadress: when a public routable address (when available)
  • lat, lon: with a low accuracy, and when the application is collecting this info already
  • cell_id, lac:  cell tower id and location area code (when available)
  • country: the ISO3166-1 code actual country (roaming, or home) when available
  • none: in any other case
Note: these location fields are defined here for completeness. Currently, due to privacy issues and app store guidelines, only country and ipaddress are collected.

Example: an iPhone app sending 2 measurements in a batch

{"app": "HelloWorld",
 "appversion": "1.3",
 "key": "aghudHZndWlkZXIMCxIGTmdDaXR5GAUM"
 "batched": true,
 "device": "Stan's phone", 
 "os_version": "iOS 4.3", 
 "model": "iPhone 4",
 "measurements": 
    [{"result": 0, 
      "error": "", 
      "when": "2011-02-17T11:07:01Z", 
      "url": "http:\/\/api.watchmouse.com\/1.6\/cp_list?callback=x", 
      "mcc": "310", 
      "mnc": "012", 
      "c_type": "3G", 
      "t_connect": 500, 
      "t_firstbyte": 3000, 
      "t_done": 5000, 
      "size": 10567}, 
     {"result": 0, 
      "error": "", 
      "when": "2011-02-17T11:09:12Z", 
      "url": "http:\/\/api.watchmouse.com\/1.6\/info_ip?callback=y", 
      "c_type": "wwan", 
      "ipaddr": "80.126.145.170",
      "t_connect": 200, 
      "t_firstbyte": 1000, 
      "t_done": 2000, 
      "size": 389}], 
 "hash": null
}

Acceptor Response

The result is a JSON object with 6 key/value pairs.
  • result: the result code, an unsigned integer, 0 meaning all went okay. Other values: see below
  • error: human readable string with English error message. Empty string when result=0
  • command: action to be executed by the client (sender of the data). The following commands are defined. If the command is not recognized, it shall be discarded, i.e. handled like noop.
    • noop: don't do anything. similar to 'snooze 0'
    • snooze: do not record any measurements for N seconds, N is specified in the arg item below
    • stop: stop recording measurements indefinitely. After this command, the IAM lib will pass all calls to the underlying iOS calls without furter action. There is no way to switch on measurements again from the Acceptor as the Acceptor will not be called anymore.
  • arg: the argument to the command above. Currently it is null for noop and stop, and a number for snooze.
  • message: a string value, being a message that should be displayed by the application to the end user. A use case for this could be to display a message like "many users experience problems with the XYZ API, please try again later". The app developer can choose if and in what case to show the message. Typically though, the developer is the one who sets up these messages to be sent on his behalf in certain situations.
  • user: an JSON object to be passed as a plist to the application.
Example: Measurement(s) received, please do not collect measurements for 10 minutes from now.
{"result": 0,
 "error": "",
 "command": "snooze",
 "arg": 600,
 "message": null,
 "user": null }


Comments