1 files changed, 59 insertions, 0 deletions
diff --git a/src/blkin/README.md b/src/blkin/README.md
new file mode 100644
index 000000000..2c8a6c99e
--- /dev/null
+++ b/src/blkin/README.md
@@ -0,0 +1,59 @@
+#blkin
+
+BlkKin is a project that enables you to trace low-overhead applications using
+LTTng following the tracing semantics that are described in Google's [Dapper
+Paper](http://static.googleusercontent.com/media/research.google.com/el//pubs/archive/36356.pdf)
+
+According to this paper the logged information is called `Annotation` and
+belongs to a specific span and trace. Each trace is comprised of multiple spans
+which are related with each other with causal relationships. So, the BlkKin
+library gives the user the API to easily instrument C/C++ applications. In
+order to instrument applications you should take a look at ``blkin-lib/tests``
+for some testcases and at the  ``blkin-lib/zipkin_c.h`` file
+
+As a tracing backend BlkKin uses LTTng. So you must have LTTng installed.
+
+In order to build and install the lib, go to blkin-lib folder and:
+
+```
+make
+make install
+```
+
+You should take a look at the examples to find out how to link the blkin lib
+with your instrumented application.
+
+In order to visualize the aggregated information you can use Twitter's
+[Zipkin](http://twitter.github.io/zipkin/) and send the data that you created,
+by running the equivalent babeltrace plugin. In order to do you can run
+
+```
+./zipkin/src/babeltrace_zipkin.py </path/to/lttng/traces> -s <server_ip>
+-p <port_number>
+
+```
+
+within the babeltrace-plugins directory.
+
+In case you have not used the blkin-lib to instrument your application, you can
+still send your data to a Scribe server. To do that you can use another
+Babeltrace plugin. This plugin tranforms LTTng trace data to a JSON format and
+sends them to a Scribe sever.To do so we can equivalently run
+
+```
+./json/src/babeltrace_json.py </path/to/lttng/traces> -s <server_ip>
+-p <port_number>
+```
+within the babeltrace-plugins directory 
+
+Both of these plugins require that you have installed Babeltrace with its
+Python bindings enabled.
+The path to the lttng traces should not be the root directory but the directory
+where the channel directories are included.
+
+## Dependencies
+
+* libboost-all-dev 
+* lttng-tools
+
+Note that BlkKin is tested only with LTTng2.4