README

This is a project to develop a mobile app and service for collecting
mobile network measurements. This is intended for experimental use
only.

Home page:
  https://github.com/Mobiperf/Mobiperf

This code is released under the Apache 2.0 License (see LICENSE for
details).

How to Contribute to this Codebase
----------------------------------

This code can be found here:
  https://github.com/Mobiperf/Mobiperf

If you wish to contribute, please read the instructions in

  docs/code-review.txt

Note that simply issuing pull requests to the Mobiperf repository
on github will not suffice.

Overview of this code
---------------------

Mobiperf consists of an Android app that collects mobile network
measurements, and a data collection server, which runs on AppEngine.

The Android app periodically checks in with the measurement server,
which sends it a list of measurement tasks to perform. Measurement tasks
include ping, traceroute, HTTP GET, and DNS lookup. Each task has an
associated set of measurement parameters (e.g., which host to ping),
and a schedule (periodicity at which to take the measurement).

The device runs the measurements in the background, and uploads the
measurement results on its next checkin cycle. By default, devices
check in with the server every hour. In order to avoid draining the
battery, the app will not take any measurements if the battery is
below a given threshold (80% by default).

The protocol spoken between the app and the server is a simple JSON
REST API, documented below.

The server is implemented using Google AppEngine. It is responsible
for managing device checkins, handing out measurement tasks, and
collecting results. It has a simple Web dashboard for presenting
measurement results to the user. There is also a mechanism for
querying measurement results.

Protocol Description
--------------------

The Mobiperf app communicates with the Mobiperf service using
the following protocol, using JSON-encoded payloads over HTTP POST
methods.

All strings representing dates and times are represented in ISO8601
format with a trailing Zindicating UTC, e.g.,
  2011-06-22T10:27:24.204589Z

/checkin - Used by devices to periodically check in with the service.

Input:

{
 "id": "device ID",
 /* Note that the user field is implied */
 "manufacturer": "device manufacturer",
 "model": "device model",
 "os": "device OS",
 "properties": {
    "timestamp": "timestamp in ISO8601 format",
    "os_version": "device OS version",
    "location": {
      "latitude": latitude value as floating point decimal degrees,
      "longitude": longitude value as floating point decimal degrees
    }
    "location_type": "location type string",
    "network_type": "network type string",
    "carrier": "carrier identifier string",
  }
}

Output: A list of JSON objects representing task descriptors for the
measurements that the device should perform. This schedule overwrites
any existing schedule on the device. Ongoing measurement tasks not
included in the new schedule are terminated immediately. If the
schedule is empty, the device will stop performing measurements.

[
  { "key": "optional task key",
    "type": "measurement type",
    "parameters": [
      { "paramName1": "paramValue1" },
      { "paramName2": "paramValue2" },
      ...
    ]
    "start_time": "task start time in ISO8601 format",
    "end_time": "task end time in ISO8601 format",
    "interval_sec": interval as an integer,
    "count": count as an integer,
    "priority": priority as an integer
  },
  { /* Additional Task... */ },
  { /* Additional Task... */ }
]

/postmeasurement - Used by the device to post a set of measurement
results to the service.

Input: JSON representation of a list of Measurement objects, with
embedded DeviceProperties.

  [ { "device_id": "device ID",
      "properties": {
      "timestamp": "timestamp in ISO8601 format",
      "os_version": "device OS version",
      "location": {
        "latitude": latitude value as floating point decimal degrees,
        "longitude": longitude value as floating point decimal degrees
       }
      "location_type": "location type string",
      "network_type": "network type string",
      "carrier": "carrier identifier string",
    }
    "type": "measurement type",
    "timestamp": "measurement timestamp in ISO8601 format",
    "success": true or false,
    "task_key": "task key associated with this measurement, if any",
    "parameters": [
        { "paramName1": "paramValue1" },
        { "paramName2": "paramValue2" },
        ...
    ],
    "values": [
        { "valueName1": "valueValue1" },
        { "valueName2": "valueValue2" },
        ...
    ],
  },
  { /* Additional Measurement... */ },
  { /* Additional Measurement... */ },
]

Output: A JSON-encoded representation of whether the post was
successful:

  { "success": true or false }

The measurement type may be "ping", "traceroute", "dns", or "http".
The parameters and measurement values for each measurement type are
given below. All parameters and values are strings (since this is how
they are represented in the JSON protocol described above).

Ping parameters

(required) target - the host name or IP address of the server to ping
(optional) packet_size_byte - the packet per ICMP ping in the unit of
bytes. Default to 56.
(optional) ping_timeout_sec - the number of seconds we wait for a ping
response. Default to 0.5.

Ping values

(required) target_ip - the IP address of the target we ping against
(required) ping_method - the actual ping method this result represents.
(ping_cmd, java_ping, http).
(required) mean_rtt_ms - Mean RTT in milliseconds (e.g.,
 "20.485" for 20.485 ms)
(required) min_rtt_ms - Min RTT in milliseconds
(required) max_rtt_ms - Max RTT in milliseconds
(required) stddev_rtt_ms - Standard deviation of RTT in milliseconds
(optional) filtered_mean_rrt_ms - Mean RRT with outlier values filtered
out. Unit is in milliseconds
(optional) packet_loss - Fraction of lost packets (e.g., "0.5" for 50% loss)

Traceroute parameters

(required) target - the hostname or IP address to use as the target of
the traceroute.
(required) packet_size_byte - the packet per ICMP ping in the unit of
bytes. Default to 56.
(optional)  ping_timeout_sec - the number of seconds we wait for a ping
response. Default to 2.
optinal ping_interval_sec - the interval between successive pings in
seconds. Default to 0.5.
optinal pings_per_hop - the number of pings we use for each ttl value.
Default to 3.
(optional) max_hop_count - the total number of hops we ping before we
declare the traceroute fails. Default to 10.

Traceroute results

(required) num_hops - Number of observed hops in the traceroute
(required) hop_N_addr_i - The ith IP address of the Nth hop along the
observed route, where N ranges from 0 to num_hops-1.
(required) hop_N_rtt_ms - Observed RTT in milliseconds to this hop.

DNS lookup parameters

(required) target - Hostname of the target to resolve
(optional) server - IP address of a DNS server to use as the resolver.
If not present, the device's default resolver is used.

DNS lookup values

(required) address - IPv4 address of the target as returned by an A
record
(required) real_hostname - True FQDN of the host that has been resolved
(required) time_ms - Time taken to perform the DNS lookup

HTTP parameters

(required) url - URL to request
(optional) method - HTTP method to use. Defaults to "GET"
(optional) headers - String (possibly containing newlines) with
additional headers to send with the request. Each header and value
pair is in the form of "headerParam:value", with different
pairs separated by "\r\n".
(optional) body - String with the request body to send (if method is
"POST")

HTTP values

(required) time_ms - Time in milliseconds to perform the complete
request
(required) code - Response code (e.g., "200")
(optional) headers_len - Size in bytes of the original response headers
(optional) body_len - Size in bytes of the original response body
(optional) headers - Response headers - may be compressed, truncated, or
elided in the case of a large response
(optional) body - Response body - may be compressed, truncated, or
elided in the case of a large response. It is a JSON encoded byte
array.