Update documentation (#102)

.gitignore

@@ -22,3 +22,4 @@ crossdock/crossdock
 crossdock/cmd/
 crossdock/scripts/
 run-crossdock.log
+site/

docs/LICENSE

@@ -0,0 +1 @@
+../LICENSE

docs/architecture.md

@@ -0,0 +1,45 @@
+#Architecture
+##Overview
+Jaeger's clients adhere to the data model described in the OpenTracing standard. Reading the [specification](https://github.com/opentracing/specification/blob/master/specification.md) will help you understand this section better.
+
+##Terminology
+###Span
+A **Span** represents a logical unit of work in the system that has an operation name, the start time of the operation, and the duration. Spans may be nested and ordered to model causal relationships. An RPC call is an example of a span.  
+
+![Traces And Spans](images/spans-traces.png)
+*Traces and Spans*
+
+###Trace
+A **Trace** is a data/execution path through the system, and can be thought of as a directed acyclic graph of spans
+
+
+##Components
+![Architecture](images/architecture.png)
+*The current Jaeger architecture*
+
+This section details the constituents of Jaeger, and how they relate to each other. It is arranged by the order in which spans from your application interact with them. 
+
+###Jaeger client
+Jaeger clients are language specific implementations of the OpenTracing API. The contain a Tracer, which is an interface for Span creation, and context propagation. 
+Some common frameworks (e.g. dropwizard) are instrumented out of the box, making it easy to get started. 
+
+An instrumented library creates spans when receiving new requests, and attaches context information (trace id, and span id) to outgoing requests. Note that only ids are propagated with requests, and any other information like operation name, logs, etc is not propagated, and is simply collected at the service by the Jaeger client.
+
+The instrumentation has very little overhead, and is designed to be always enabled in production.
+
+Note that while all traces are instrumented, only few are sampled. Sampling a trace marks the trace for further processing and storage. 
+By default, Jaeger client samples 0.0001% of traces, and has the ability to retrieve to retrieve sampler parameters from the agent. 
+
+![Context propagation explained](images/context-prop.png)
+*Context propagation*
+
+###Agent
+A network daemon that lists for spans sent over UDP, which it batches and sends to the collector. It is designed to be deployed to all hosts as an infrastructure component.  The agent abstracts the routing and discovery of the collectors away from the client. 
+
+###Collector
+The collector receives traces from Jaeger agents, runs them through a processing pipeline. Currently our pipeline validates traces, indexes them, performs any transformations, and finally stores them. 
+Our storage is a pluggable component, which currently supports Cassandra. 
+
+###Query
+Query is a service that retrieves traces from storage, and hosts a UI to display them. 
+

docs/client_libraries.md

@@ -0,0 +1,16 @@
+#Client Libraries
+
+##Official libraries
+
+| Language | Library                                                      | 
+| ---------|--------------------------------------------------------------|
+| go       | [jaeger-go](https://github.com/uber/jaeger-client-go)        |
+| java     | [jaeger-java](https://github.com/uber/jaeger-client-java)    |
+| node     | [jaeger-node](https://github.com/uber/jaeger-client-node)    |
+| python   | [jaeger-python](https://github.com/uber/jaeger-client-python)|
+
+For a deep dive into how to instrument a Go service, look at [Tracing HTTP request latency](https://medium.com/@YuriShkuro/tracing-http-request-latency-in-go-with-opentracing-7cc1282a100a).
+
+##OpenTracing Contributions
+
+See the OpenTracing contributions repository on [Github](https://github.com/opentracing-contrib) for more libraries. 

docs/contributing.md

@@ -0,0 +1 @@
+../CONTRIBUTING.md

docs/getting_started.md

@@ -1,63 +1,75 @@
-#Getting Started with Jaeger
+#Getting Started
 
-We're working hard on making all backend components of Jaeger open
-source. Please watch the GitHub repository
-<https://github.com/uber/jaeger> for updates.
+##All in one Docker image 
+This image, designed for quick local testing, launches the Jaeger UI, collector, query, and agent, with an in memory storage component. 
 
-Jaeger client libraries are already open source and for now can be used
-with Zipkin backend. You can see a HOW-TO example in the blog post
-[Tracing HTTP request latency in Go with
-OpenTracing](https://medium.com/@YuriShkuro/tracing-http-request-latency-in-go-with-opentracing-7cc1282a100a).
+The simplest way to start the all in one docker image is to use the pre-built image published to DockerHub.
 
-##Running Jaeger in Docker Container
-
-Coming soon...
+```bash
+docker run -d -p5775:5775/udp -p16686:16686 jaegertracing/all-in-one:latest
+```
 
-##Tracing a Sample Application
-**Hot R.O.D. - Rides on Demand**
+You can then navigate to `http://localhost:16686` to access the Jaeger UI. 
 
-<https://github.com/uber/jaeger/tree/master/examples/hotrod>
+##Sample Application
+###HotROD (Rides on Demand)###
 
 This is a demo application that consists of several microservices and
 illustrates the use of the [OpenTracing API](http://opentracing.io).
 
 It can be run standalone, but requires Jaeger backend to view the
 traces.
 
-### Features
+####Features
 
 -   Discover architecture of the whole system via data-driven dependency
-    diagram
--   View request timeline & errors, understand how the app works
--   Find sources of latency, lack of concurrency
--   Highly contextualized logging
+    diagram.
+-   View request time line & errors, understand how the app works.
+-   Find sources of latency, lack of concurrency.
+-   Highly contextualized logging.
 -   Use baggage propagation to
 
-    -   Diagnose inter-request contention (queueing)
-    -   Attribute time spent in a service
+    -   Diagnose inter-request contention (queueing).
+    -   Attribute time spent in a service.
 
 -   Use open source libraries with OpenTracing integration to get
-    vendor-neutral instrumentation for free
+    vendor-neutral instrumentation for free.
 
-### Prerequisites
+####Prerequisites
 
 -   You need Go 1.7 or higher installed on your machine.
--   Requires a running Jaeger backend to view the traces.
-    -   See [Running Jaeger backend in docker](#running-jaeger-in-docker-container)
+-   Requires a [running Jaeger backend](#all-in-one-docker-image) to view the traces.
 
-### Installation
+####Running 
 
-```shell 
+```bash
 go get github.com/uber/jaeger
+cd $GOPATH/src/github.com/uber/jaeger
 make install_examples
+cd examples/hotrod
+go run ./main.go all
 ```
 
-### Running
+Then navigate to `http://localhost:8080`.
 
-```shell
-cd examples/hotrod
-go run ./main.go all
+##Client Libraries
+
+Look [here](client_libraries.md).
+
+##Running individual components
+Individual components can be run from source. They have their `main.go` in the `cmd` folder. 
+
+For e.g., to run the agent, you'll have to do the following
+
+```bash
+go get github.com/uber/jaeger
+cd $GOPATH/src/github.com/uber/jaeger
+make install
+go run ./cmd/agent/main.go
 ```
 
-Then open <http://127.0.0.1:8080>
+##Migrating from Zipkin
+Jaeger's agent and collector can also accept [Zipkin](http://zipkin.io/) [Spans](https://github.com/openzipkin/zipkin-api/blob/master/thrift/zipkinCore.thrift#L381), and transform them to Jaeger's data model before storage. 
 
+Both of them support this Zipkin [idl](https://github.com/uber/jaeger-idl/blob/master/thrift/zipkincore.thrift), and expose the `ZipkinCollector` service.
+On the agent, `ZipkinCollector` is available on `UDP` port `5775`, and uses the `TBinaryProtocol`.