| License | BSD |
| ReleasedLast Release | May 2016 |
Maintained by Lorenzo Primiterra, Antonio Langiu, Simone Basso.
MeasurementKit is a library that implements open network measurement methodologies (performance, censorship, etc.) and targets mobile platforms (Android and iOS).
It is meant to be embedeed by third party applications with specific network measurement needs and/or to be used by researchers as a basis to implement novel tools.
Currently it implements the following high-level tests:
OONI's DNS Injection test
OONI's HTTP Invalid Request Line test
OONI's TCP Connect test
It contains building-block functionalities useful to implement your own tests. More in detail it currently implements:
TCP connection (with which you can create a TCP connection towards and endpoint, receive and send data)
DNS client (with which you can resolve and reverse-resolve A and AAAA records using arbitrary name servers)
HTTP client (with which you can send HTTP/1.1 requests and receive and parse the corresponding responses)
traceroute for Android (with which you can send individual traceroute probes with a specified payload and TTL)
In the short term we plan to add to MeasurementKit:
the network diagnostic tool network performance test
the functionality to communicate with the OONI backend
more OONI tests
Other functionalities that we would like to add are building-blocks functionalities such as uTP, and traceroute for iOS.
The following index illustrates the content of the remainder of this file:
To clone MeasurementKit repository, do:
git clone https://github.com/measurement-kit/measurement-kit
If you need to checkout a specific branch (say feature/foo) for testing
it, clone the repository and then type:
git fetch origin
git checkout feature/foo
Then proceed with the instruction to build and test MeasurementKit.
To build, MeasurementKit needs:
C++11 must be enabled, otherwise certain C++11 features such as
std::function will not be recognized.
MeasurementKit includes and unconditionally compiles the sources of the following projects:
MeasurementKit also depends on the following projects (which are only conditionally compiled as explained below):
The ./configure script should check whether all
the dependencies are in place and should configure the compilers
properly. If a dependency is not found, ./configure will
fall back to the copy of the dependency stored under the
src/ext directory.
The vanilla build process is the following:
autoreconf -i
./configure
make
You can also force ./configure to select dependencies available
at specific directories using the following flags:
--with-libevent=PREFIX that tells ./configure to use the
libevent library and headers installed at PREFIX
--with-yaml-cpp=PREFIX that tells ./configure to use the
yaml-cpp library and headers installed at PREFIX
--with-boost=PREFIX that tells ./configure to use the
boost headers installed at PREFIX
--with-jansson=PREFIX that tells ./configure to use the
jansson library and headers installed at PREFIX
--with-libmaxminddb=PREFIX that tells ./configure to use the
libmaxminddb library and headers installed at PREFIX
In all the above cases you can also specify PREFIX equal to
builtin to force ./configure to use builtin sources.
For example,
/opt/local (meaning that event.h
is /opt/local/include/event.h and that libevent.a is
/opt/local/lib/libevent.a), use ./configure --with-libevent=/opt/local
./configure --with-libevent=builtin
Once you have built MeasurementKit, to compile and run the unit test programs, run:
make check
To tell make to produce less output (as in the Linux kernel build process) run:
make V=0
To compile MeasurementKit for Android, see the README.md file contained in
the mobile/android directory of this repository.
To compile and use MeasurementKit for iOS, do the following on a MacOSX system where XCode and its command line tools have been installed:
./mobile/ios/scripts/build.sh
The Cocoapods podspec hasn't been submitted yet, but you can already use it in your project adding this line in your Podfile:
pod 'measurement_kit', :git => 'https://github.com/measurement-kit/measurement-kit.git'
You can include another branch with:
pod 'measurement_kit',
:git => 'https://github.com/measurement-kit/measurement-kit.git'
:branch => 'branch_name'
Then type pod install and open .xcworkspace file (beware not to open the
.xcodeproj file instead, because that alone won't compile).
The following examples show how to use OONI library.
This first example show how to run a synchronous test. That is, in the following example, the run call is going to block until the test is complete. (Note that in this case the test may or may not run in the context of the same thread that called run).
#include <measurement_kit/ooni.hpp>
// Run sync test
mk::ooni::HttpInvalidRequestLineTest()
.set_backend("http://127.0.0.1/")
.set_verbose()
.on_log([](const char *s) {
// If needed, acquire the proper locks
// Process incoming log line
})
.run();
// Note: run() returns when test is completeIn this second example, instead, we show how to run an asynchronous test. In this case, run returns immediately, the test runs in a background thread, and the callback passed as argument to run is invoked when the test completed.
// Run async test
mk::ooni::HttpInvalidRequestLineTest()
.set_backend("http://127.0.0.1/")
.set_verbose()
.on_log([](const char *s) {
// If needed, acquire the proper locks
// Process incoming log line
})
.run([]() {
// If needed, acquire the proper locks
// Handle test completion
});
// Note: run() returns immediately, callback called when doneIn both cases, you need to be careful inside the callbacks, because in general they may be called from background threads.
You can find documentation of MeasurementKit C++ API in the doc/api folder of the repository.