README

Welcome to the Brown University implementation of X-Trace.

Version 3.0 of X-Trace was developed at Brown University.  
It is a slimmed down version of X-Trace with an emphasis on performance.  
Some code has been inherited or reused from the Berkeley implementation of X-Trace 2.0.

X-Trace is a framework for tracing the execution of distributed system.  
Out of the box, X-Trace 3.0 offers two main features
* A metadata serialization format and propagation API
* A logging API and database server

Usage:

X-Trace version 3 requires protocol buffers.  Ensure that the protoc executable is on your path.
https://code.google.com/p/protobuf/

X-Trace version 3 requires the Brown University Systems pubsub package, available from github
https://github.com/brownsys/pubsub

To run a clean build and install:
mvn clean package install appassembler:assemble

To run performance tests to measure costs of metadata propagation and logging:
mvn integration-test

X-Trace is configurable using the typesafe config.  Default configuration values are defined in the reference.conf.
You can override these reference values by defining new values in an application.conf and placing it on your classpath.
Configuration values can also be passed using the standard java system properties command line format, 
eg. -Dxtrace.server.hostname=8.8.8.8 

Implementation status:
The X-Trace version 3 implementation is partially complete.  Extensive testing, and implementation of PubSub as a report source,
remains incomplete.

Metadata format:

The X-Trace metadata format is completely overhauled and it is incompatible with the metadata format from version 2.
This is a tough decision, but ultimately moving to protocol buffers for serialization will prove useful in future
in terms of extensibility and performance.


Client APIs:

The metadata propagation API and client logging API are brand new.  They are quite concise.  The logging API currently uses
Brown University Pub-Sub as the transport mechanism, which itself is built on Zero-MQ. 


Server:

The X-Trace server reuses much code from X-Trace version 2.  Specifically, the Derby metadata store, file tree data store,
and web front-ends remain in place.  Much of it has been refactored and cruft removed.  Whilst the X-Trace version 3 metadata
format and logging APIs are brand new, the X-Trace version 3 server is backwards compatibile with applications instrumented
with previous versions of X-Trace.