By the power of Docker, I compel you!
This PR changes the doc generator script to use Docker images for all
the weird utilities. That includes Thrift itself, so now we have
explicit control over which version of Thrift is used to generate the
docs. I opted for the latest one, which seems to have some minor
differences in the generated HTML. FWIW, I prefer the new look.
This PR also regenerates the docs.
It also downgrades tidy by 5 patch versions. Whatevs.
diff --git a/generate_thrift_v1_docs/generate.sh b/generate_thrift_v1_docs/generate.sh
index b34e043..b44463f 100755
--- a/generate_thrift_v1_docs/generate.sh
+++ b/generate_thrift_v1_docs/generate.sh
@@ -4,16 +4,19 @@
set -x
# Where's Waldo?
-me="$(readlink -f ${BASH_SOURCE[0]})"
-[ $? -gt 0 ] && me="${BASH_SOURCE[0]}"
-mydir="$(cd "$(dirname "$me")" && pwd -P)"
-rootdir="$(cd $(dirname "$mydir") && pwd -P)"
+[ ! -d ./generate_thrift_v1_docs ] && cd ..
+if [ ! -d ./generate_thrift_v1_docs ]; then
+ echo "Please run this script either from the root of the openzipkin.github.io repository"
+ echo "or from the generate_thrift_v1_docs folder in that repository."
+ exit 1
+fi
+
+rootdir="$(pwd -P)"
target_root="${rootdir}/public"
target_dir="${target_root}/thrift/v1"
# Prepare clean output space
rm -rfv "$target_dir"
-mkdir -p "$target_dir"
# Prepare clean workspace
cd "$(mktemp -d)"
@@ -25,20 +28,25 @@
for source in *.thrift; do
echo "include \"$source\"" >> wrapper.thrift
done
-thrift -r --gen html -I . -out "$target_dir" wrapper.thrift
+mkdir html
+docker run --rm -v "$PWD:/workspace" -u "$(id -u)" thrift:0.11 \
+ thrift -r --gen html -I /workspace -out "/workspace/html" /workspace/wrapper.thrift
# Turn Thrift-output index.html into valid XML
# HTML Tidy exists with 1 on warnings, and we _will_ have warnings
set +e
-tidy -indent -asxml -output "$target_dir/index.tidy.html" "$target_dir/index.html"
+docker run --rm -v "$PWD:/workspace" -u "$(id -u)" imega/tidy \
+ -indent -asxml -output "/workspace/html/index.tidy.html" "/workspace/html/index.html"
tidy_status=$?
[ $tidy_status -gt 1 ] && exit $tidy_status
set -e
# Apply some transforms to the generated HTML
-java -jar /usr/share/java/Saxon-HE.jar \
- -s:"$target_dir/index.tidy.html" \
- -xsl:"$mydir/transform.xslt" \
- -o:"$target_dir/index.baked.html"
-mv -v "$target_dir/index.baked.html" "$target_dir/index.html"
-rm -v "$target_dir/index.tidy.html"
+cp "$rootdir/generate_thrift_v1_docs/transform.xslt" ./
+docker run --rm -v "$PWD:/workspace" -u "$(id -u)" klakegg/saxon \
+ -s:/workspace/html/index.tidy.html \
+ -xsl:/workspace/transform.xslt \
+ -o:/workspace/html/index.baked.html
+mv -v html/index.baked.html html/index.html
+rm -v html/index.tidy.html
+mv html "$target_dir"
diff --git a/public/thrift/v1/index.html b/public/thrift/v1/index.html
index 0edc658..ac87c20 100644
--- a/public/thrift/v1/index.html
+++ b/public/thrift/v1/index.html
@@ -3,7 +3,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
- <meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.2.0" />
+ <meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.1.25" />
<link href="style.css" rel="stylesheet" type="text/css" />
diff --git a/public/thrift/v1/zipkinCore.html b/public/thrift/v1/zipkinCore.html
index 91fe9f0..bbf5094 100644
--- a/public/thrift/v1/zipkinCore.html
+++ b/public/thrift/v1/zipkinCore.html
@@ -45,185 +45,186 @@
</tr></table>
<hr/><h2 id="Constants">Constants</h2>
<table class="table-bordered table-striped table-condensed"><thead><th>Constant</th><th>Type</th><th>Value</th></thead>
-<tr id="Const_CLIENT_SEND"><td><code>CLIENT_SEND</code></td><td><code>string</code></td><td><code>"cs"</code></td></tr><tr><td colspan="3"><blockquote>The client sent ("cs") a request to a server. There is only one send per
+<tr id="Const_CLIENT_SEND"><td><code>CLIENT_SEND</code></td><td><code>string</code></td><td><code>"cs"</code></td></tr><tr><td colspan="3"><blockquote><pre>The client sent ("cs") a request to a server. There is only one send per
span. For example, if there's a transport error, each attempt can be logged
as a WIRE_SEND annotation.
-<p/>
+
If chunking is involved, each chunk could be logged as a separate
CLIENT_SEND_FRAGMENT in the same span.
-<p/>
+
Annotation.host is not the server. It is the host which logged the send
event, almost always the client. When logging CLIENT_SEND, instrumentation
should also log the SERVER_ADDR.
-<br/></blockquote></td></tr><tr id="Const_CLIENT_RECV"><td><code>CLIENT_RECV</code></td><td><code>string</code></td><td><code>"cr"</code></td></tr><tr><td colspan="3"><blockquote>The client received ("cr") a response from a server. There is only one
+</pre><br/></blockquote></td></tr><tr id="Const_CLIENT_RECV"><td><code>CLIENT_RECV</code></td><td><code>string</code></td><td><code>"cr"</code></td></tr><tr><td colspan="3"><blockquote><pre>The client received ("cr") a response from a server. There is only one
receive per span. For example, if duplicate responses were received, each
can be logged as a WIRE_RECV annotation.
-<p/>
+
If chunking is involved, each chunk could be logged as a separate
CLIENT_RECV_FRAGMENT in the same span.
-<p/>
+
Annotation.host is not the server. It is the host which logged the receive
event, almost always the client. The actual endpoint of the server is
recorded separately as SERVER_ADDR when CLIENT_SEND is logged.
-<br/></blockquote></td></tr><tr id="Const_SERVER_SEND"><td><code>SERVER_SEND</code></td><td><code>string</code></td><td><code>"ss"</code></td></tr><tr><td colspan="3"><blockquote>The server sent ("ss") a response to a client. There is only one response
+</pre><br/></blockquote></td></tr><tr id="Const_SERVER_SEND"><td><code>SERVER_SEND</code></td><td><code>string</code></td><td><code>"ss"</code></td></tr><tr><td colspan="3"><blockquote><pre>The server sent ("ss") a response to a client. There is only one response
per span. If there's a transport error, each attempt can be logged as a
WIRE_SEND annotation.
-<p/>
+
Typically, a trace ends with a server send, so the last timestamp of a trace
is often the timestamp of the root span's server send.
-<p/>
+
If chunking is involved, each chunk could be logged as a separate
SERVER_SEND_FRAGMENT in the same span.
-<p/>
+
Annotation.host is not the client. It is the host which logged the send
event, almost always the server. The actual endpoint of the client is
recorded separately as CLIENT_ADDR when SERVER_RECV is logged.
-<br/></blockquote></td></tr><tr id="Const_SERVER_RECV"><td><code>SERVER_RECV</code></td><td><code>string</code></td><td><code>"sr"</code></td></tr><tr><td colspan="3"><blockquote>The server received ("sr") a request from a client. There is only one
+</pre><br/></blockquote></td></tr><tr id="Const_SERVER_RECV"><td><code>SERVER_RECV</code></td><td><code>string</code></td><td><code>"sr"</code></td></tr><tr><td colspan="3"><blockquote><pre>The server received ("sr") a request from a client. There is only one
request per span. For example, if duplicate responses were received, each
can be logged as a WIRE_RECV annotation.
-<p/>
+
Typically, a trace starts with a server receive, so the first timestamp of a
trace is often the timestamp of the root span's server receive.
-<p/>
+
If chunking is involved, each chunk could be logged as a separate
SERVER_RECV_FRAGMENT in the same span.
-<p/>
+
Annotation.host is not the client. It is the host which logged the receive
event, almost always the server. When logging SERVER_RECV, instrumentation
should also log the CLIENT_ADDR.
-<br/></blockquote></td></tr><tr id="Const_MESSAGE_SEND"><td><code>MESSAGE_SEND</code></td><td><code>string</code></td><td><code>"ms"</code></td></tr><tr><td colspan="3"><blockquote>Message send ("ms") is a request to send a message to a destination, usually
+</pre><br/></blockquote></td></tr><tr id="Const_MESSAGE_SEND"><td><code>MESSAGE_SEND</code></td><td><code>string</code></td><td><code>"ms"</code></td></tr><tr><td colspan="3"><blockquote><pre>Message send ("ms") is a request to send a message to a destination, usually
a broker. This may be the only annotation in a messaging span. If WIRE_SEND
exists in the same span, it follows this moment and clarifies delays sending
the message, such as batching.
-<p/>
+
Unlike RPC annotations like CLIENT_SEND, messaging spans never share a span
ID. For example, "ms" should always be the parent of "mr".
-<p/>
+
Annotation.host is not the destination, it is the host which logged the send
event: the producer. When annotating MESSAGE_SEND, instrumentation should
also tag the MESSAGE_ADDR.
-<br/></blockquote></td></tr><tr id="Const_MESSAGE_RECV"><td><code>MESSAGE_RECV</code></td><td><code>string</code></td><td><code>"mr"</code></td></tr><tr><td colspan="3"><blockquote>A consumer received ("mr") a message from a broker. This may be the only
+</pre><br/></blockquote></td></tr><tr id="Const_MESSAGE_RECV"><td><code>MESSAGE_RECV</code></td><td><code>string</code></td><td><code>"mr"</code></td></tr><tr><td colspan="3"><blockquote><pre>A consumer received ("mr") a message from a broker. This may be the only
annotation in a messaging span. If WIRE_RECV exists in the same span, it
precedes this moment and clarifies any local queuing delay.
-<p/>
+
Unlike RPC annotations like SERVER_RECV, messaging spans never share a span
ID. For example, "mr" should always be a child of "ms" unless it is a root
span.
-<p/>
+
Annotation.host is not the broker, it is the host which logged the receive
event: the consumer. When annotating MESSAGE_RECV, instrumentation should
also tag the MESSAGE_ADDR.
-<br/></blockquote></td></tr><tr id="Const_WIRE_SEND"><td><code>WIRE_SEND</code></td><td><code>string</code></td><td><code>"ws"</code></td></tr><tr><td colspan="3"><blockquote>Optionally logs an attempt to send a message on the wire. Multiple wire send
+</pre><br/></blockquote></td></tr><tr id="Const_WIRE_SEND"><td><code>WIRE_SEND</code></td><td><code>string</code></td><td><code>"ws"</code></td></tr><tr><td colspan="3"><blockquote><pre>Optionally logs an attempt to send a message on the wire. Multiple wire send
events could indicate network retries. A lag between client or server send
and wire send might indicate queuing or processing delay.
-<br/></blockquote></td></tr><tr id="Const_WIRE_RECV"><td><code>WIRE_RECV</code></td><td><code>string</code></td><td><code>"wr"</code></td></tr><tr><td colspan="3"><blockquote>Optionally logs an attempt to receive a message from the wire. Multiple wire
+</pre><br/></blockquote></td></tr><tr id="Const_WIRE_RECV"><td><code>WIRE_RECV</code></td><td><code>string</code></td><td><code>"wr"</code></td></tr><tr><td colspan="3"><blockquote><pre>Optionally logs an attempt to receive a message from the wire. Multiple wire
receive events could indicate network retries. A lag between wire receive
and client or server receive might indicate queuing or processing delay.
-<br/></blockquote></td></tr><tr id="Const_CLIENT_SEND_FRAGMENT"><td><code>CLIENT_SEND_FRAGMENT</code></td><td><code>string</code></td><td><code>"csf"</code></td></tr><tr><td colspan="3"><blockquote>Optionally logs progress of a (CLIENT_SEND, WIRE_SEND). For example, this
+</pre><br/></blockquote></td></tr><tr id="Const_CLIENT_SEND_FRAGMENT"><td><code>CLIENT_SEND_FRAGMENT</code></td><td><code>string</code></td><td><code>"csf"</code></td></tr><tr><td colspan="3"><blockquote><pre>Optionally logs progress of a (CLIENT_SEND, WIRE_SEND). For example, this
could be one chunk in a chunked request.
-<br/></blockquote></td></tr><tr id="Const_CLIENT_RECV_FRAGMENT"><td><code>CLIENT_RECV_FRAGMENT</code></td><td><code>string</code></td><td><code>"crf"</code></td></tr><tr><td colspan="3"><blockquote>Optionally logs progress of a (CLIENT_RECV, WIRE_RECV). For example, this
+</pre><br/></blockquote></td></tr><tr id="Const_CLIENT_RECV_FRAGMENT"><td><code>CLIENT_RECV_FRAGMENT</code></td><td><code>string</code></td><td><code>"crf"</code></td></tr><tr><td colspan="3"><blockquote><pre>Optionally logs progress of a (CLIENT_RECV, WIRE_RECV). For example, this
could be one chunk in a chunked response.
-<br/></blockquote></td></tr><tr id="Const_SERVER_SEND_FRAGMENT"><td><code>SERVER_SEND_FRAGMENT</code></td><td><code>string</code></td><td><code>"ssf"</code></td></tr><tr><td colspan="3"><blockquote>Optionally logs progress of a (SERVER_SEND, WIRE_SEND). For example, this
+</pre><br/></blockquote></td></tr><tr id="Const_SERVER_SEND_FRAGMENT"><td><code>SERVER_SEND_FRAGMENT</code></td><td><code>string</code></td><td><code>"ssf"</code></td></tr><tr><td colspan="3"><blockquote><pre>Optionally logs progress of a (SERVER_SEND, WIRE_SEND). For example, this
could be one chunk in a chunked response.
-<br/></blockquote></td></tr><tr id="Const_SERVER_RECV_FRAGMENT"><td><code>SERVER_RECV_FRAGMENT</code></td><td><code>string</code></td><td><code>"srf"</code></td></tr><tr><td colspan="3"><blockquote>Optionally logs progress of a (SERVER_RECV, WIRE_RECV). For example, this
+</pre><br/></blockquote></td></tr><tr id="Const_SERVER_RECV_FRAGMENT"><td><code>SERVER_RECV_FRAGMENT</code></td><td><code>string</code></td><td><code>"srf"</code></td></tr><tr><td colspan="3"><blockquote><pre>Optionally logs progress of a (SERVER_RECV, WIRE_RECV). For example, this
could be one chunk in a chunked request.
-<br/></blockquote></td></tr><tr id="Const_HTTP_HOST"><td><code>HTTP_HOST</code></td><td><code>string</code></td><td><code>"http.host"</code></td></tr><tr><td colspan="3"><blockquote>The domain portion of the URL or host header. Ex. "mybucket.s3.amazonaws.com"
-<p/>
+</pre><br/></blockquote></td></tr><tr id="Const_HTTP_HOST"><td><code>HTTP_HOST</code></td><td><code>string</code></td><td><code>"http.host"</code></td></tr><tr><td colspan="3"><blockquote><pre>The domain portion of the URL or host header. Ex. "mybucket.s3.amazonaws.com"
+
Used to filter by host as opposed to ip address.
-<br/></blockquote></td></tr><tr id="Const_HTTP_METHOD"><td><code>HTTP_METHOD</code></td><td><code>string</code></td><td><code>"http.method"</code></td></tr><tr><td colspan="3"><blockquote>The HTTP method, or verb, such as "GET" or "POST".
-<p/>
+</pre><br/></blockquote></td></tr><tr id="Const_HTTP_METHOD"><td><code>HTTP_METHOD</code></td><td><code>string</code></td><td><code>"http.method"</code></td></tr><tr><td colspan="3"><blockquote><pre>The HTTP method, or verb, such as "GET" or "POST".
+
Used to filter against an http route.
-<br/></blockquote></td></tr><tr id="Const_HTTP_PATH"><td><code>HTTP_PATH</code></td><td><code>string</code></td><td><code>"http.path"</code></td></tr><tr><td colspan="3"><blockquote>The absolute http path, without any query parameters. Ex. "/objects/abcd-ff"
-<p/>
+</pre><br/></blockquote></td></tr><tr id="Const_HTTP_PATH"><td><code>HTTP_PATH</code></td><td><code>string</code></td><td><code>"http.path"</code></td></tr><tr><td colspan="3"><blockquote><pre>The absolute http path, without any query parameters. Ex. "/objects/abcd-ff"
+
Used as a filter or to clarify the request path for a given route. For example, the path for
a route "/objects/:objectId" could be "/objects/abdc-ff". This does not limit cardinality like
HTTP_ROUTE("http.route") can, so is not a good input to a span name.
-<p/>
+
The Zipkin query api only supports equals filters. Dropping query parameters makes the number
of distinct URIs less. For example, one can query for the same resource, regardless of signing
parameters encoded in the query line. Dropping query parameters also limits the security impact
of this tag.
-<p/>
+
Historical note: This was commonly expressed as "http.uri" in zipkin, even though it was most
-<br/></blockquote></td></tr><tr id="Const_HTTP_ROUTE"><td><code>HTTP_ROUTE</code></td><td><code>string</code></td><td><code>"http.route"</code></td></tr><tr><td colspan="3"><blockquote>The route which a request matched or "" (empty string) if routing is supported, but there was no
-match. Ex "/objects/{objectId}"
-<p/>
-Often used as a span name when known, with empty routes coercing to "not_found" or "redirected"
-based on HTTP_STATUS_CODE("http.status_code").
-<p/>
+</pre><br/></blockquote></td></tr><tr id="Const_HTTP_ROUTE"><td><code>HTTP_ROUTE</code></td><td><code>string</code></td><td><code>"http.route"</code></td></tr><tr><td colspan="3"><blockquote><pre>The route which a request matched or "" (empty string) if routing is supported, but there was no
+match. Ex "/users/{userId}"
+
Unlike HTTP_PATH("http.path"), this value is fixed cardinality, so is a safe input to a span
name function or a metrics dimension. Different formats are possible. For example, the following
-are all valid route templates: "/objects" "/objects/:objectId" "/objects/*"
-<br/></blockquote></td></tr><tr id="Const_HTTP_URL"><td><code>HTTP_URL</code></td><td><code>string</code></td><td><code>"http.url"</code></td></tr><tr><td colspan="3"><blockquote>The entire URL, including the scheme, host and query parameters if available. Ex.
+are all valid route templates: "/users" "/users/:userId" "/users/*"
+
+Route-based span name generation often uses other tags, such as HTTP_METHOD("http.method") and
+HTTP_STATUS_CODE("http.status_code"). Route-based names can look like "get /users/{userId}",
+"post /users", "get not_found" or "get redirected".
+</pre><br/></blockquote></td></tr><tr id="Const_HTTP_URL"><td><code>HTTP_URL</code></td><td><code>string</code></td><td><code>"http.url"</code></td></tr><tr><td colspan="3"><blockquote><pre>The entire URL, including the scheme, host and query parameters if available. Ex.
"https://mybucket.s3.amazonaws.com/objects/abcd-ff?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Algorithm=AWS4-HMAC-SHA256..."
-<p/>
+
Combined with HTTP_METHOD, you can understand the fully-qualified request line.
-<p/>
+
This is optional as it may include private data or be of considerable length.
-<br/></blockquote></td></tr><tr id="Const_HTTP_STATUS_CODE"><td><code>HTTP_STATUS_CODE</code></td><td><code>string</code></td><td><code>"http.status_code"</code></td></tr><tr><td colspan="3"><blockquote>The HTTP status code, when not in 2xx range. Ex. "503"
-<p/>
+</pre><br/></blockquote></td></tr><tr id="Const_HTTP_STATUS_CODE"><td><code>HTTP_STATUS_CODE</code></td><td><code>string</code></td><td><code>"http.status_code"</code></td></tr><tr><td colspan="3"><blockquote><pre>The HTTP status code, when not in 2xx range. Ex. "503"
+
Used to filter for error status.
-<br/></blockquote></td></tr><tr id="Const_HTTP_REQUEST_SIZE"><td><code>HTTP_REQUEST_SIZE</code></td><td><code>string</code></td><td><code>"http.request.size"</code></td></tr><tr><td colspan="3"><blockquote>The size of the non-empty HTTP request body, in bytes. Ex. "16384"
-<p/>
+</pre><br/></blockquote></td></tr><tr id="Const_HTTP_REQUEST_SIZE"><td><code>HTTP_REQUEST_SIZE</code></td><td><code>string</code></td><td><code>"http.request.size"</code></td></tr><tr><td colspan="3"><blockquote><pre>The size of the non-empty HTTP request body, in bytes. Ex. "16384"
+
Large uploads can exceed limits or contribute directly to latency.
-<br/></blockquote></td></tr><tr id="Const_HTTP_RESPONSE_SIZE"><td><code>HTTP_RESPONSE_SIZE</code></td><td><code>string</code></td><td><code>"http.response.size"</code></td></tr><tr><td colspan="3"><blockquote>The size of the non-empty HTTP response body, in bytes. Ex. "16384"
-<p/>
+</pre><br/></blockquote></td></tr><tr id="Const_HTTP_RESPONSE_SIZE"><td><code>HTTP_RESPONSE_SIZE</code></td><td><code>string</code></td><td><code>"http.response.size"</code></td></tr><tr><td colspan="3"><blockquote><pre>The size of the non-empty HTTP response body, in bytes. Ex. "16384"
+
Large downloads can exceed limits or contribute directly to latency.
-<br/></blockquote></td></tr><tr id="Const_LOCAL_COMPONENT"><td><code>LOCAL_COMPONENT</code></td><td><code>string</code></td><td><code>"lc"</code></td></tr><tr><td colspan="3"><blockquote>The value of "lc" is the component or namespace of a local span.
-<p/>
+</pre><br/></blockquote></td></tr><tr id="Const_LOCAL_COMPONENT"><td><code>LOCAL_COMPONENT</code></td><td><code>string</code></td><td><code>"lc"</code></td></tr><tr><td colspan="3"><blockquote><pre>The value of "lc" is the component or namespace of a local span.
+
BinaryAnnotation.host adds service context needed to support queries.
-<p/>
+
Local Component("lc") supports three key features: flagging, query by
service and filtering Span.name by namespace.
-<p/>
+
While structurally the same, local spans are fundamentally different than
RPC spans in how they should be interpreted. For example, zipkin v1 tools
center on RPC latency and service graphs. Root local-spans are neither
indicative of critical path RPC latency, nor have impact on the shape of a
service graph. By flagging with "lc", tools can special-case local spans.
-<p/>
+
Zipkin v1 Spans are unqueryable unless they can be indexed by service name.
The only path to a service name is by (Binary)?Annotation.host.serviceName.
By logging "lc", a local span can be queried even if no other annotations
are logged.
-<p/>
+
The value of "lc" is the namespace of Span.name. For example, it might be
"finatra2", for a span named "bootstrap". "lc" allows you to resolves
conflicts for the same Span.name, for example "finatra/bootstrap" vs
"finch/bootstrap". Using local component, you'd search for spans named
"bootstrap" where "lc=finch"
-<br/></blockquote></td></tr><tr id="Const_ERROR"><td><code>ERROR</code></td><td><code>string</code></td><td><code>"error"</code></td></tr><tr><td colspan="3"><blockquote>When an annotation value, this indicates when an error occurred. When a
+</pre><br/></blockquote></td></tr><tr id="Const_ERROR"><td><code>ERROR</code></td><td><code>string</code></td><td><code>"error"</code></td></tr><tr><td colspan="3"><blockquote><pre>When an annotation value, this indicates when an error occurred. When a
binary annotation key, the value is a human readable message associated
with an error.
-<p/>
+
Due to transient errors, an ERROR annotation should not be interpreted
as a span failure, even the annotation might explain additional latency.
Instrumentation should add the ERROR binary annotation when the operation
failed and couldn't be recovered.
-<p/>
+
Here's an example: A span has an ERROR annotation, added when a WIRE_SEND
failed. Another WIRE_SEND succeeded, so there's no ERROR binary annotation
on the span because the overall operation succeeded.
-<p/>
+
Note that RPC spans often include both client and server hosts: It is
possible that only one side perceived the error.
-<br/></blockquote></td></tr><tr id="Const_CLIENT_ADDR"><td><code>CLIENT_ADDR</code></td><td><code>string</code></td><td><code>"ca"</code></td></tr><tr><td colspan="3"><blockquote>Indicates a client address ("ca") in a span. Most likely, there's only one.
+</pre><br/></blockquote></td></tr><tr id="Const_CLIENT_ADDR"><td><code>CLIENT_ADDR</code></td><td><code>string</code></td><td><code>"ca"</code></td></tr><tr><td colspan="3"><blockquote><pre>Indicates a client address ("ca") in a span. Most likely, there's only one.
Multiple addresses are possible when a client changes its ip or port within
a span.
-<br/></blockquote></td></tr><tr id="Const_SERVER_ADDR"><td><code>SERVER_ADDR</code></td><td><code>string</code></td><td><code>"sa"</code></td></tr><tr><td colspan="3"><blockquote>Indicates a server address ("sa") in a span. Most likely, there's only one.
+</pre><br/></blockquote></td></tr><tr id="Const_SERVER_ADDR"><td><code>SERVER_ADDR</code></td><td><code>string</code></td><td><code>"sa"</code></td></tr><tr><td colspan="3"><blockquote><pre>Indicates a server address ("sa") in a span. Most likely, there's only one.
Multiple addresses are possible when a client is redirected, or fails to a
different server ip or port.
-<br/></blockquote></td></tr><tr id="Const_MESSAGE_ADDR"><td><code>MESSAGE_ADDR</code></td><td><code>string</code></td><td><code>"ma"</code></td></tr><tr><td colspan="3"><blockquote>Indicates the remote address of a messaging span, usually the broker.
-<br/></blockquote></td></tr></table><hr/><h2 id="Enumerations">Enumerations</h2>
+</pre><br/></blockquote></td></tr><tr id="Const_MESSAGE_ADDR"><td><code>MESSAGE_ADDR</code></td><td><code>string</code></td><td><code>"ma"</code></td></tr><tr><td colspan="3"><blockquote><pre>Indicates the remote address of a messaging span, usually the broker.
+</pre><br/></blockquote></td></tr></table><hr/><h2 id="Enumerations">Enumerations</h2>
<div class="definition"><h3 id="Enum_AnnotationType">Enumeration: AnnotationType</h3>
-A subset of thrift base types, except BYTES.
-<br/><br/><table class="table-bordered table-striped table-condensed">
+<pre>A subset of thrift base types, except BYTES.
+</pre><br/><br/><table class="table-bordered table-striped table-condensed">
<tr><td><code>BOOL</code></td><td><code>0</code></td><td>
-Set to 0x01 when key is CLIENT_ADDR or SERVER_ADDR
-<br/></td></tr>
+<pre>Set to 0x01 when key is CLIENT_ADDR or SERVER_ADDR
+</pre><br/></td></tr>
<tr><td><code>BYTES</code></td><td><code>1</code></td><td>
-No encoding, or type is unknown.
-<br/></td></tr>
+<pre>No encoding, or type is unknown.
+</pre><br/></td></tr>
<tr><td><code>I16</code></td><td><code>2</code></td><td>
</td></tr>
<tr><td><code>I32</code></td><td><code>3</code></td><td>
@@ -233,72 +234,161 @@
<tr><td><code>DOUBLE</code></td><td><code>5</code></td><td>
</td></tr>
<tr><td><code>STRING</code></td><td><code>6</code></td><td>
-the only type zipkin v1 supports search against.
-<br/></td></tr>
+<pre>the only type zipkin v1 supports search against.
+</pre><br/></td></tr>
</table></div>
<hr/><h2 id="Structs">Data structures</h2>
<div class="definition"><h3 id="Struct_Endpoint">Struct: Endpoint</h3>
<table class="table-bordered table-striped table-condensed"><thead><th>Key</th><th>Field</th><th>Type</th><th>Description</th><th>Requiredness</th><th>Default value</th></thead>
-<tr><td>1</td><td>ipv4</td><td><code>i32</code></td><td>IPv4 host address packed into 4 bytes.<br/><br/>Ex for the ip 1.2.3.4, it would be (1 << 24) | (2 << 16) | (3 << 8) | 4<br/></td><td>default</td><td></td></tr>
-<tr><td>2</td><td>port</td><td><code>i16</code></td><td>IPv4 port or 0, if unknown.<br/><br/>Note: this is to be treated as an unsigned integer, so watch for negatives.<br/></td><td>default</td><td></td></tr>
-<tr><td>3</td><td>service_name</td><td><code>string</code></td><td>Classifier of a source or destination in lowercase, such as "zipkin-web".<br/><br/>This is the primary parameter for trace lookup, so should be intuitive as<br/>possible, for example, matching names in service discovery.<br/><br/>Conventionally, when the service name isn't known, service_name = "unknown".<br/>However, it is also permissible to set service_name = "" (empty string).<br/>The difference in the latter usage is that the span will not be queryable<br/>by service name unless more information is added to the span with non-empty<br/>service name, e.g. an additional annotation from the server.<br/><br/>Particularly clients may not have a reliable service name at ingest. One<br/>approach is to set service_name to "" at ingest, and later assign a<br/>better label based on binary annotations, such as user agent.<br/></td><td>default</td><td></td></tr>
-<tr><td>4</td><td>ipv6</td><td><code>binary</code></td><td>IPv6 host address packed into 16 bytes. Ex Inet6Address.getBytes()<br/></td><td>optional</td><td></td></tr>
-</table><br/>Indicates the network context of a service recording an annotation with two
+<tr><td>1</td><td>ipv4</td><td><code>i32</code></td><td>IPv4 host address packed into 4 bytes.
+
+Ex for the ip 1.2.3.4, it would be (1 << 24) | (2 << 16) | (3 << 8) | 4
+></td><td>default</td><td></td></tr>
+<tr><td>2</td><td>port</td><td><code>i16</code></td><td>IPv4 port or 0, if unknown.
+
+Note: this is to be treated as an unsigned integer, so watch for negatives.
+</td><td>default</td><td></td></tr>
+<tr><td>3</td><td>service_name</td><td><code>string</code></td><td>Classifier of a source or destination in lowercase, such as "zipkin-web".
+
+This is the primary parameter for trace lookup, so should be intuitive as
+possible, for example, matching names in service discovery.
+
+Conventionally, when the service name isn't known, service_name = "unknown".
+However, it is also permissible to set service_name = "" (empty string).
+The difference in the latter usage is that the span will not be queryable
+by service name unless more information is added to the span with non-empty
+service name, e.g. an additional annotation from the server.
+
+Particularly clients may not have a reliable service name at ingest. One
+approach is to set service_name to "" at ingest, and later assign a
+better label based on binary annotations, such as user agent.
+</td><td>default</td><td></td></tr>
+<tr><td>4</td><td>ipv6</td><td><code>binary</code></td><td>IPv6 host address packed into 16 bytes. Ex Inet6Address.getBytes()
+</td><td>optional</td><td></td></tr>
+</table><br/><pre>Indicates the network context of a service recording an annotation with two
exceptions.
-<p/>
+
When a BinaryAnnotation, and key is CLIENT_ADDR or SERVER_ADDR,
the endpoint indicates the source or destination of an RPC. This exception
allows zipkin to display network context of uninstrumented services, or
clients such as web browsers.
-<br/></div><div class="definition"><h3 id="Struct_Annotation">Struct: Annotation</h3>
+</pre><br/></div><div class="definition"><h3 id="Struct_Annotation">Struct: Annotation</h3>
<table class="table-bordered table-striped table-condensed"><thead><th>Key</th><th>Field</th><th>Type</th><th>Description</th><th>Requiredness</th><th>Default value</th></thead>
-<tr><td>1</td><td>timestamp</td><td><code>i64</code></td><td>Microseconds from epoch.<br/><br/>This value should use the most precise value possible. For example,<br/>gettimeofday or multiplying currentTimeMillis by 1000.<br/></td><td>default</td><td></td></tr>
-<tr><td>2</td><td>value</td><td><code>string</code></td><td>Usually a short tag indicating an event, like "sr" or "finagle.retry".<br/></td><td>default</td><td></td></tr>
-<tr><td>3</td><td>host</td><td><code><a href="zipkinCore.html#Struct_Endpoint">Endpoint</a></code></td><td>The host that recorded the value, primarily for query by service name.<br/></td><td>optional</td><td></td></tr>
-</table><br/>Associates an event that explains latency with a timestamp.
-<p/>
+<tr><td>1</td><td>timestamp</td><td><code>i64</code></td><td>Microseconds from epoch.
+
+This value should use the most precise value possible. For example,
+gettimeofday or multiplying currentTimeMillis by 1000.
+</td><td>default</td><td></td></tr>
+<tr><td>2</td><td>value</td><td><code>string</code></td><td>Usually a short tag indicating an event, like "sr" or "finagle.retry".
+</td><td>default</td><td></td></tr>
+<tr><td>3</td><td>host</td><td><code><a href="#Struct_Endpoint">Endpoint</a></code></td><td>The host that recorded the value, primarily for query by service name.
+</td><td>optional</td><td></td></tr>
+</table><br/><pre>Associates an event that explains latency with a timestamp.
+
Unlike log statements, annotations are often codes: for example "sr".
-<br/></div><div class="definition"><h3 id="Struct_BinaryAnnotation">Struct: BinaryAnnotation</h3>
+</pre><br/></div><div class="definition"><h3 id="Struct_BinaryAnnotation">Struct: BinaryAnnotation</h3>
<table class="table-bordered table-striped table-condensed"><thead><th>Key</th><th>Field</th><th>Type</th><th>Description</th><th>Requiredness</th><th>Default value</th></thead>
-<tr><td>1</td><td>key</td><td><code>string</code></td><td>Name used to lookup spans, such as "http.path" or "finagle.version".<br/></td><td>default</td><td></td></tr>
-<tr><td>2</td><td>value</td><td><code>binary</code></td><td>Serialized thrift bytes, in TBinaryProtocol format.<br/><br/>For legacy reasons, byte order is big-endian. See THRIFT-3217.<br/></td><td>default</td><td></td></tr>
-<tr><td>3</td><td>annotation_type</td><td><code><a href="zipkinCore.html#Enum_AnnotationType">AnnotationType</a></code></td><td>The thrift type of value, most often STRING.<br/><br/>annotation_type shouldn't vary for the same key.<br/></td><td>default</td><td></td></tr>
-<tr><td>4</td><td>host</td><td><code><a href="zipkinCore.html#Struct_Endpoint">Endpoint</a></code></td><td>The host that recorded value, allowing query by service name or address.<br/><br/>There are two exceptions: when key is "ca" or "sa", this is the source or<br/>destination of an RPC. This exception allows zipkin to display network<br/>context of uninstrumented services, such as browsers or databases.<br/></td><td>optional</td><td></td></tr>
-</table><br/>Binary annotations are tags applied to a Span to give it context. For
+<tr><td>1</td><td>key</td><td><code>string</code></td><td>Name used to lookup spans, such as "http.path" or "finagle.version".
+</td><td>default</td><td></td></tr>
+<tr><td>2</td><td>value</td><td><code>binary</code></td><td>Serialized thrift bytes, in TBinaryProtocol format.
+
+For legacy reasons, byte order is big-endian. See THRIFT-3217.
+</td><td>default</td><td></td></tr>
+<tr><td>3</td><td>annotation_type</td><td><code><a href="#Enum_AnnotationType">AnnotationType</a></code></td><td>The thrift type of value, most often STRING.
+
+annotation_type shouldn't vary for the same key.
+</td><td>default</td><td></td></tr>
+<tr><td>4</td><td>host</td><td><code><a href="#Struct_Endpoint">Endpoint</a></code></td><td>The host that recorded value, allowing query by service name or address.
+
+There are two exceptions: when key is "ca" or "sa", this is the source or
+destination of an RPC. This exception allows zipkin to display network
+context of uninstrumented services, such as browsers or databases.
+</td><td>optional</td><td></td></tr>
+</table><br/><pre>Binary annotations are tags applied to a Span to give it context. For
example, a binary annotation of HTTP_PATH ("http.path") could the path
to a resource in a RPC call.
-<p/>
+
Binary annotations of type STRING are always queryable, though more a
historical implementation detail than a structural concern.
-<p/>
+
Binary annotations can repeat, and vary on the host. Similar to Annotation,
the host indicates who logged the event. This allows you to tell the
difference between the client and server side of the same key. For example,
the key "http.path" might be different on the client and server side due to
rewriting, like "/api/v1/myresource" vs "/myresource. Via the host field,
you can see the different points of view, which often help in debugging.
-<br/></div><div class="definition"><h3 id="Struct_Span">Struct: Span</h3>
+</pre><br/></div><div class="definition"><h3 id="Struct_Span">Struct: Span</h3>
<table class="table-bordered table-striped table-condensed"><thead><th>Key</th><th>Field</th><th>Type</th><th>Description</th><th>Requiredness</th><th>Default value</th></thead>
-<tr><td>1</td><td>trace_id</td><td><code>i64</code></td><td>Unique 8-byte identifier for a trace, set on all spans within it.<br/></td><td>default</td><td></td></tr>
-<tr><td>3</td><td>name</td><td><code>string</code></td><td>Span name in lowercase, rpc method for example. Conventionally, when the<br/>span name isn't known, name = "unknown".<br/></td><td>default</td><td></td></tr>
-<tr><td>4</td><td>id</td><td><code>i64</code></td><td>Unique 8-byte identifier of this span within a trace. A span is uniquely<br/>identified in storage by (trace_id, id).<br/></td><td>default</td><td></td></tr>
-<tr><td>5</td><td>parent_id</td><td><code>i64</code></td><td>The parent's Span.id; absent if this the root span in a trace.<br/></td><td>optional</td><td></td></tr>
-<tr><td>6</td><td>annotations</td><td><code>list<<code><a href="zipkinCore.html#Struct_Annotation">Annotation</a></code>></code></td><td>Associates events that explain latency with a timestamp. Unlike log<br/>statements, annotations are often codes: for example SERVER_RECV("sr").<br/>Annotations are sorted ascending by timestamp.<br/></td><td>default</td><td></td></tr>
-<tr><td>8</td><td>binary_annotations</td><td><code>list<<code><a href="zipkinCore.html#Struct_BinaryAnnotation">BinaryAnnotation</a></code>></code></td><td>Tags a span with context, usually to support query or aggregation. For<br/>example, a binary annotation key could be "http.path".<br/></td><td>default</td><td></td></tr>
-<tr><td>9</td><td>debug</td><td><code>bool</code></td><td>True is a request to store this span even if it overrides sampling policy.<br/></td><td>optional</td><td>0</td></tr>
-<tr><td>10</td><td>timestamp</td><td><code>i64</code></td><td>Epoch microseconds of the start of this span, absent if this an incomplete<br/>span.<br/><br/>This value should be set directly by instrumentation, using the most<br/>precise value possible. For example, gettimeofday or syncing nanoTime<br/>against a tick of currentTimeMillis.<br/><br/>For compatibility with instrumentation that precede this field, collectors<br/>or span stores can derive this via Annotation.timestamp.<br/>For example, SERVER_RECV.timestamp or CLIENT_SEND.timestamp.<br/><br/>Timestamp is nullable for input only. Spans without a timestamp cannot be<br/>presented in a timeline: Span stores should not output spans missing a<br/>timestamp.<br/><br/>There are two known edge-cases where this could be absent: both cases<br/>exist when a collector receives a span in parts and a binary annotation<br/>precedes a timestamp. This is possible when..<br/> - The span is in-flight (ex not yet received a timestamp)<br/> - The span's start event was lost<br/></td><td>optional</td><td></td></tr>
-<tr><td>11</td><td>duration</td><td><code>i64</code></td><td>Measurement in microseconds of the critical path, if known. Durations of<br/>less than one microsecond must be rounded up to 1 microsecond.<br/><br/>This value should be set directly, as opposed to implicitly via annotation<br/>timestamps. Doing so encourages precision decoupled from problems of<br/>clocks, such as skew or NTP updates causing time to move backwards.<br/><br/>For compatibility with instrumentation that precede this field, collectors<br/>or span stores can derive this by subtracting Annotation.timestamp.<br/>For example, SERVER_SEND.timestamp - SERVER_RECV.timestamp.<br/><br/>If this field is persisted as unset, zipkin will continue to work, except<br/>duration query support will be implementation-specific. Similarly, setting<br/>this field non-atomically is implementation-specific.<br/><br/>This field is i64 vs i32 to support spans longer than 35 minutes.<br/></td><td>optional</td><td></td></tr>
-<tr><td>12</td><td>trace_id_high</td><td><code>i64</code></td><td>Optional unique 8-byte additional identifier for a trace. If non zero, this<br/>means the trace uses 128 bit traceIds instead of 64 bit.<br/></td><td>optional</td><td></td></tr>
-</table><br/>A trace is a series of spans (often RPC calls) which form a latency tree.
-<p/>
+<tr><td>1</td><td>trace_id</td><td><code>i64</code></td><td>Unique 8-byte identifier for a trace, set on all spans within it.
+</td><td>default</td><td></td></tr>
+<tr><td>3</td><td>name</td><td><code>string</code></td><td>Span name in lowercase, rpc method for example. Conventionally, when the
+span name isn't known, name = "unknown".
+</td><td>default</td><td></td></tr>
+<tr><td>4</td><td>id</td><td><code>i64</code></td><td>Unique 8-byte identifier of this span within a trace. A span is uniquely
+identified in storage by (trace_id, id).
+</td><td>default</td><td></td></tr>
+<tr><td>5</td><td>parent_id</td><td><code>i64</code></td><td>The parent's Span.id; absent if this the root span in a trace.
+</td><td>optional</td><td></td></tr>
+<tr><td>6</td><td>annotations</td><td><code>list<<code><a href="#Struct_Annotation">Annotation</a></code>></code></td><td>Associates events that explain latency with a timestamp. Unlike log
+statements, annotations are often codes: for example SERVER_RECV("sr").
+Annotations are sorted ascending by timestamp.
+</td><td>default</td><td></td></tr>
+<tr><td>8</td><td>binary_annotations</td><td><code>list<<code><a href="#Struct_BinaryAnnotation">BinaryAnnotation</a></code>></code></td><td>Tags a span with context, usually to support query or aggregation. For
+example, a binary annotation key could be "http.path".
+</td><td>default</td><td></td></tr>
+<tr><td>9</td><td>debug</td><td><code>bool</code></td><td>True is a request to store this span even if it overrides sampling policy.
+</td><td>optional</td><td><code>false</code></td></tr>
+<tr><td>10</td><td>timestamp</td><td><code>i64</code></td><td>Epoch microseconds of the start of this span, absent if this an incomplete
+span.
+
+This value should be set directly by instrumentation, using the most
+precise value possible. For example, gettimeofday or syncing nanoTime
+against a tick of currentTimeMillis.
+
+For compatibility with instrumentation that precede this field, collectors
+or span stores can derive this via Annotation.timestamp.
+For example, SERVER_RECV.timestamp or CLIENT_SEND.timestamp.
+
+Timestamp is nullable for input only. Spans without a timestamp cannot be
+presented in a timeline: Span stores should not output spans missing a
+timestamp.
+
+There are two known edge-cases where this could be absent: both cases
+exist when a collector receives a span in parts and a binary annotation
+precedes a timestamp. This is possible when..
+ - The span is in-flight (ex not yet received a timestamp)
+ - The span's start event was lost
+</td><td>optional</td><td></td></tr>
+<tr><td>11</td><td>duration</td><td><code>i64</code></td><td>Measurement in microseconds of the critical path, if known. Durations of
+less than one microsecond must be rounded up to 1 microsecond.
+
+This value should be set directly, as opposed to implicitly via annotation
+timestamps. Doing so encourages precision decoupled from problems of
+clocks, such as skew or NTP updates causing time to move backwards.
+
+For compatibility with instrumentation that precede this field, collectors
+or span stores can derive this by subtracting Annotation.timestamp.
+For example, SERVER_SEND.timestamp - SERVER_RECV.timestamp.
+
+If this field is persisted as unset, zipkin will continue to work, except
+duration query support will be implementation-specific. Similarly, setting
+this field non-atomically is implementation-specific.
+
+This field is i64 vs i32 to support spans longer than 35 minutes.
+</td><td>optional</td><td></td></tr>
+<tr><td>12</td><td>trace_id_high</td><td><code>i64</code></td><td>Optional unique 8-byte additional identifier for a trace. If non zero, this
+means the trace uses 128 bit traceIds instead of 64 bit.
+</td><td>optional</td><td></td></tr>
+</table><br/><pre>A trace is a series of spans (often RPC calls) which form a latency tree.
+
Spans are usually created by instrumentation in RPC clients or servers, but
can also represent in-process activity. Annotations in spans are similar to
log statements, and are sometimes created directly by application developers
to indicate events of interest, such as a cache miss.
-<p/>
+
The root span is where parent_id = Nil; it usually has the longest duration
in the trace.
-<p/>
+
Span identifiers are packed into i64s, but should be treated opaquely.
String encoding is fixed-width lower-hex, to avoid signed interpretation.
-<br/></div></div></body></html>
+</pre><br/></div></div></body></html>
diff --git a/public/thrift/v1/zipkinDependencies.html b/public/thrift/v1/zipkinDependencies.html
index ae9588f..191929a 100644
--- a/public/thrift/v1/zipkinDependencies.html
+++ b/public/thrift/v1/zipkinDependencies.html
@@ -18,13 +18,19 @@
<hr/><h2 id="Structs">Data structures</h2>
<div class="definition"><h3 id="Struct_DependencyLink">Struct: DependencyLink</h3>
<table class="table-bordered table-striped table-condensed"><thead><th>Key</th><th>Field</th><th>Type</th><th>Description</th><th>Requiredness</th><th>Default value</th></thead>
-<tr><td>1</td><td>parent</td><td><code>string</code></td><td>parent service name (caller)<br/></td><td>default</td><td></td></tr>
-<tr><td>2</td><td>child</td><td><code>string</code></td><td>child service name (callee)<br/></td><td>default</td><td></td></tr>
-<tr><td>4</td><td>callCount</td><td><code>i64</code></td><td>total traced calls made from parent to child<br/></td><td>default</td><td></td></tr>
-<tr><td>5</td><td>errorCount</td><td><code>i64</code></td><td>how many calls are known to be errors<br/></td><td>default</td><td></td></tr>
+<tr><td>1</td><td>parent</td><td><code>string</code></td><td>parent service name (caller)
+</td><td>default</td><td></td></tr>
+<tr><td>2</td><td>child</td><td><code>string</code></td><td>child service name (callee)
+</td><td>default</td><td></td></tr>
+<tr><td>4</td><td>callCount</td><td><code>i64</code></td><td>total traced calls made from parent to child
+</td><td>default</td><td></td></tr>
+<tr><td>5</td><td>errorCount</td><td><code>i64</code></td><td>how many calls are known to be errors
+</td><td>default</td><td></td></tr>
</table><br/></div><div class="definition"><h3 id="Struct_Dependencies">Struct: Dependencies</h3>
<table class="table-bordered table-striped table-condensed"><thead><th>Key</th><th>Field</th><th>Type</th><th>Description</th><th>Requiredness</th><th>Default value</th></thead>
-<tr><td>1</td><td>start_ts</td><td><code>i64</code></td><td>milliseconds from epoch<br/></td><td>default</td><td></td></tr>
-<tr><td>2</td><td>end_ts</td><td><code>i64</code></td><td>milliseconds from epoch<br/></td><td>default</td><td></td></tr>
-<tr><td>3</td><td>links</td><td><code>list<<code><a href="zipkinDependencies.html#Struct_DependencyLink">DependencyLink</a></code>></code></td><td></td><td>default</td><td></td></tr>
+<tr><td>1</td><td>start_ts</td><td><code>i64</code></td><td>milliseconds from epoch
+</td><td>default</td><td></td></tr>
+<tr><td>2</td><td>end_ts</td><td><code>i64</code></td><td>milliseconds from epoch
+</td><td>default</td><td></td></tr>
+<tr><td>3</td><td>links</td><td><code>list<<code><a href="#Struct_DependencyLink">DependencyLink</a></code>></code></td><td></td><td>default</td><td></td></tr>
</table><br/></div></div></body></html>
