Merge pull request #14 from chimericalidea/final_edits
Final edits
diff --git a/Gemfile.lock b/Gemfile.lock
index bad7b96..49f79dd 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -21,14 +21,14 @@
multipart-post (>= 1.2, < 3)
ffi (1.9.10)
gemoji (2.1.0)
- github-pages (66)
+ github-pages (67)
RedCloth (= 4.2.9)
github-pages-health-check (= 1.1.0)
jekyll (= 3.0.3)
jekyll-coffeescript (= 1.0.1)
jekyll-feed (= 0.4.0)
jekyll-gist (= 1.4.0)
- jekyll-github-metadata (= 1.9.0)
+ jekyll-github-metadata (= 1.10.0)
jekyll-mentions (= 1.1.2)
jekyll-paginate (= 1.1.0)
jekyll-redirect-from (= 0.10.0)
@@ -68,7 +68,7 @@
jekyll-feed (0.4.0)
jekyll-gist (1.4.0)
octokit (~> 4.2)
- jekyll-github-metadata (1.9.0)
+ jekyll-github-metadata (1.10.0)
octokit (~> 4.0)
jekyll-mentions (1.1.2)
html-pipeline (~> 2.3)
@@ -112,7 +112,7 @@
redcarpet (3.3.3)
rouge (1.10.1)
safe_yaml (1.0.4)
- sass (3.4.21)
+ sass (3.4.22)
sawyer (0.7.0)
addressable (>= 2.3.5, < 2.5)
faraday (~> 0.8, < 0.10)
@@ -127,8 +127,8 @@
ruby
DEPENDENCIES
- github-pages (= 66)
+ github-pages (= 67)
json
BUNDLED WITH
- 1.11.2
+ 1.12.0.pre.2
diff --git a/index.md b/index.md
index 54b2429..2541962 100644
--- a/index.md
+++ b/index.md
@@ -7,16 +7,11 @@
Zipkin is a distributed tracing system. It helps gather timing data needed to
troubleshoot latency problems in microservice architectures. It manages both the
-collection and lookup of this data through a Collector and a Query service.
+collection and lookup of this data.
Zipkin’s design is based on the
[Google Dapper](http://research.google.com/pubs/pub36356.html) paper.
-Collecting traces helps developers gain deeper knowledge about how certain
-requests perform in a distributed system. Let’s say we’re having problems with
-user requests timing out. We can look up traced requests that timed out and
-display it in the web UI. We’ll be able to quickly find the service responsible
-for adding the unexpected response time. If the service has been annotated
-adequately we can also find out where in that service the issue is happening.
+Applications are instrumented to report timing data to Zipkin. The Zipkin UI also presents a Dependency diagram showing how many traced requests went through each application. If you are troubleshooting latency problems or errors, you can filter or sort all traces based on the application, length of trace, annotation, or timestamp. Once you select a trace, you can see the percentage of the total trace time each span takes which allows you to identify the problem application.
## Where to go next?
diff --git a/pages/architecture.md b/pages/architecture.md
index 60763e7..de55c42 100644
--- a/pages/architecture.md
+++ b/pages/architecture.md
@@ -4,53 +4,50 @@
---
-These are the components that make up a fully fledged tracing system.
-
-
Instrumented libraries
----------------------
Tracing information is collected on each host using the instrumented libraries
and sent to Zipkin. When the host makes a request to another service, it passes
-a few tracing identifers along with the request so we can later tie the data
+a few tracing identifiers along with the request so we can later tie the data
together.
To see if an instrumentation library already exists for your platform, see the
-list of [existing instrumentations]({{ site.github.url
-}}/pages/existing_instrumentations).
+list of [existing instrumentations]({{ site.github.url}}/pages/existing_instrumentations).
+
+
Transport
---------
-Spans must be transported from the services being traced to Zipkin collectors.
-There are two primary transports, Scribe and Kafka. Scribe is deprecated.
+Spans sent by the instrumented library must be transported from the services being traced to Zipkin collectors.
+There are two primary transports: Scribe and Kafka. Scribe is shown in the figure. See [Span Receivers]({{ site.github.url }}/pages/span_receivers) for more information.
-Zipkin Collector
-----------------
+There are 4 components that make up Zipkin:
+* collector
+* storage
+* search
+* web UI
-Once the trace data arrives at the Zipkin collector daemon we check that it's
-valid, store it and the index it for lookups.
+### Zipkin Collector
-Storage
--------
+Once the trace data arrives at the Zipkin collector daemon, it is validated, stored, and indexed for lookups by the Zipkin collector.
-We originally built Zipkin on Cassandra for storage. It's scalable, has a
+### Storage
+
+Zipkin was initially built to store data on Cassandra since Cassandra is scalable, has a
flexible schema, and is heavily used within Twitter. However, we made this
-component pluggable, and we now have support for Redis and MySQL.
+component pluggable. In addition to Cassandra, we support Redis and MySQL.
-Zipkin Query Service
---------------------
+### Zipkin Query Service
-Once the data is stored and indexed we need a way to extract it. This is where
-the query daemon comes in, providing a simple JSON api for finding and retrieving
-traces. The primary consumer of this api is the Web UI.
+Once the data is stored and indexed, we need a way to extract it. The query daemon provides a simple JSON API for finding and retrieving traces. The primary consumer of this API is the Web UI.
-Web UI
-------
+### Web UI
-A GUI that presents a nice face for viewing traces. The web UI provides a
-method for viewing traces based on service, time, and annotations. Note
-that there is no built in authentication in the UI.
+We created a GUI that presents a nice interface for viewing traces. The web UI provides a
+method for viewing traces based on service, time, and annotations.
+Note: there is no built-in authentication in the UI!
diff --git a/pages/existing_instrumentations.md b/pages/existing_instrumentations.md
index bf45052..33581a5 100644
--- a/pages/existing_instrumentations.md
+++ b/pages/existing_instrumentations.md
@@ -4,8 +4,8 @@
---
Tracing information is collected on each host using the instrumented libraries
-and sent to Zipkin. When the host makes a request to another service, it propagates
-a few tracing identifiers along with the request so we can later tie the data
+and sent to Zipkin. When the host makes a request to another application, it passes
+a few tracing identifiers along with the request to Zipkin so we can later tie the data
together into spans.
The following libraries exist to provide instrumentation on various platforms.
diff --git a/pages/instrumenting.md b/pages/instrumenting.md
index 1d19716..78765c4 100644
--- a/pages/instrumenting.md
+++ b/pages/instrumenting.md
@@ -4,19 +4,25 @@
This is an advanced topic. Before reading further, you may want to check whether
an instrumentation library for your platform [already exists]({{ site.github.url
-}}/pages/existing_instrumentations).
+}}/pages/existing_instrumentations). If not and if you want to take on creating an instrumentation library, first things first; jump on
+[Zipkin Gitter chat channel](https://gitter.im/openzipkin/zipkin) and let us know. We'll be extremely
+happy to help you along the way.
{: .message}
-So you want to send traces to Zipkin, and there is no existing library for your
-platform. If you want to take on creating an instrumentation library, here's
-what you'll need to do. First things first: jump on
-[Zipkin Gitter chat channel](https://gitter.im/openzipkin/zipkin). We'll be extremely
-happy to help you along the way.
+Overview
+=======
+To instrument a library, you'll need to understand and create the following elements:
+1. Core data structures - the information that is collected and sent to Zipkin
+1. Trace identifiers - what tags for the information are needed so it can be reassembled in a logical order by Zipkin
+ * Generating identifiers - how to generate these Ids and which ids should be inherited
+ * Communicating trace information - additional information that is sent to Zipkin along with the traces and their IDs.
+
+
Alright, ready? Here we go.
Core data structures
---------------------
+=====
First, there are a core set of structures that we need:
@@ -27,13 +33,13 @@
* **cs** - Client Start. The client has made the request. This sets the
beginning of the span.
-* **sr** - Server Receive. The server has received the request and will start
+* **sr** - Server Receive: The server has received the request and will start
processing it. The difference between this and `cs` will be combination of
network latency and clock jitter.
-* **ss** - Server Send. The server has completed processing and has sent the
+* **ss** - Server Send: The server has completed processing and has sent the
request back to the client. The difference between this and `ss` will be the
amount of time it took the server to process the request.
-* **cr** - Client Recieve. The client has received the response from the server.
+* **cr** - Client Receiver: The client has received the response from the server.
This sets the end of the span. The RPC is considered complete when this
annotation is recorded.
@@ -46,7 +52,7 @@
**BinaryAnnotation**
Binary annotations do not have a time component. They are meant to provide extra
-information about the RPC. For instance, when calling an HTTP service providing
+information about the RPC. For instance when calling an HTTP service, providing
the URI of the call will help with later analysis of requests coming into the
service.
@@ -64,9 +70,9 @@
through the system.
Trace identifiers
------------------
+=====
-In order to reassmble a set of spans into a full trace three pieces of
+In order to reassemble a set of spans into a full trace three pieces of
information are required. These are all 64 bits long.
**Trace Id**
@@ -109,27 +115,25 @@
-------------------------------
Trace information needs to be passed between upstream and downstream services in
-order to reassemble a complete trace. Five pieces of information are required:
+order to reassemble a complete trace. Five pieces of information are required:
* Trace Id
* Span Id
* Parent Id
-* Is Sampled
-* Flags
-
-"Is Sampled" lets the downstream service know if it should record trace
+* Sampled - Lets the downstream service know if it should record trace
information for the request.
-
-"Flags" provide the ability to create and communicate feature flags. This is how
+* Flags - Provides the ability to create and communicate feature flags. This is how
we can tell downstream services that this is a "debug" request.
-Finagle provides mechanisms for passing this information with Http and Thrift
+Check [here](https://github.com/openzipkin/brave/blob/e474ed1e1cd291c7ebc6830c58fdba0a6318fdd2/brave-http/src/main/java/com/github/kristofa/brave/http/BraveHttpHeaders.java) for the format
+
+Finagle provides mechanisms for passing this information with HTTP and Thrift
requests. Other protocols will need to be augmented with the information for
tracing to be effective.
-**Http Tracing**
+**HTTP Tracing**
-Http headers are used to pass along trace information:
+HTTP headers are used to pass along trace information.
The B3 portion of the header is so named for the original name of Zipkin:
BigBrotherBird.
diff --git a/pages/span_receivers.md b/pages/span_receivers.md
index a34b767..d564dbc 100644
--- a/pages/span_receivers.md
+++ b/pages/span_receivers.md
@@ -1,21 +1,8 @@
---
-title: Span Receivers
+title: Transports
---
-A `SpanReceiver` is responsible for collecting spans from services, converting
+A transport is responsible for collecting spans from services, converting
them to a Zipkin common Span, and passing them to the storage layer. This
-approach is modular which allows for receivers that accept any type of data
-from any producer. Zipkin comes with a receiver for Scribe and one for
-Kafka.
-
-Scribe Receiver
----------------
-
-Scribe was the logging framework in use at Twitter to transport trace data when
-Zipkin was created.
-------
-
-For small architectures, tracers can be setup to send directly to the Zipkin
-collectors. The ScribeSpanReceiver expects a Scribe log entry with a Base64-encoded, binary serialized thrift Span using the "zipkin" category. This
-category is configurable via a command line flag. Finagle-Zipkin does this
-automatically.
+approach is modular which allows for transports that accept any type of data
+from any producer. Zipkin comes with transports for HTTP, Kafka, and Scribe.
