From 45ae8070b712163f6e13fc2214b7bc2341407f45 Mon Sep 17 00:00:00 2001 From: Zoltan Nagy Date: Sun, 28 Jan 2018 17:13:46 +0100 Subject: [PATCH 1/2] Generate documentation from `zipkin-api` Thrift definitions --- generate_docs_from_thrift.sh | 15 +++ public/thrift/index.html | 51 ++++++++++ public/thrift/style.css | 184 +++++++++++++++++++++++++++++++++++ public/thrift/wrapper.html | 16 +++ 4 files changed, 266 insertions(+) create mode 100755 generate_docs_from_thrift.sh create mode 100644 public/thrift/index.html create mode 100644 public/thrift/style.css create mode 100644 public/thrift/wrapper.html diff --git a/generate_docs_from_thrift.sh b/generate_docs_from_thrift.sh new file mode 100755 index 0000000..5eb6ebb --- /dev/null +++ b/generate_docs_from_thrift.sh @@ -0,0 +1,15 @@ +#!/bin/bash + +set -euo pipefail +set -x + +target_root="$(pwd)/public" +cd "$(mktemp -d)" +git clone https://github.com/openzipkin/zipkin-api.git +cd zipkin-api/thrift +rm -fv wrapper.thrift +for source in *.thrift; do + echo "include \"$source\"" >> wrapper.thrift +done +thrift --gen html wrapper.thrift +mv gen-html "$target_root/thrift" diff --git a/public/thrift/index.html b/public/thrift/index.html new file mode 100644 index 0000000..0d38ff3 --- /dev/null +++ b/public/thrift/index.html @@ -0,0 +1,51 @@ + + +All Thrift declarations +
+

All Thrift declarations

+ + + + + + + + + + + + + +
ModuleServicesData typesConstants
wrapper
zipkinCoreAnnotation
+AnnotationType
+BinaryAnnotation
+Endpoint
+Span
+		CLIENT_ADDR
+CLIENT_RECV
+CLIENT_RECV_FRAGMENT
+CLIENT_SEND
+CLIENT_SEND_FRAGMENT
+ERROR
+HTTP_HOST
+HTTP_METHOD
+HTTP_PATH
+HTTP_REQUEST_SIZE
+HTTP_RESPONSE_SIZE
+HTTP_STATUS_CODE
+HTTP_URL
+LOCAL_COMPONENT
+MESSAGE_ADDR
+MESSAGE_RECV
+MESSAGE_SEND
+SERVER_ADDR
+SERVER_RECV
+SERVER_RECV_FRAGMENT
+SERVER_SEND
+SERVER_SEND_FRAGMENT
+WIRE_RECV
+WIRE_SEND
+
zipkinDependenciesDependencies
+DependencyLink
+
+
diff --git a/public/thrift/style.css b/public/thrift/style.css new file mode 100644 index 0000000..34fd9d7 --- /dev/null +++ b/public/thrift/style.css @@ -0,0 +1,184 @@ +/*! + * Bootstrap v2.0.3 + * + * Copyright 2012 Twitter, Inc + * Licensed under the Apache License v2.0 + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Designed and built with all the love in the world @twitter by @mdo and @fat. + */ +.clearfix{*zoom:1;}.clearfix:before,.clearfix:after{display:table;content:"";} +.clearfix:after{clear:both;} +.hide-text{font:0/0 a;color:transparent;text-shadow:none;background-color:transparent;border:0;} +.input-block-level{display:block;width:100%;min-height:28px;-webkit-box-sizing:border-box;-moz-box-sizing:border-box;-ms-box-sizing:border-box;box-sizing:border-box;} +article,aside,details,figcaption,figure,footer,header,hgroup,nav,section{display:block;} +audio,canvas,video{display:inline-block;*display:inline;*zoom:1;} +audio:not([controls]){display:none;} +html{font-size:100%;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%;} +a:focus{outline:thin dotted #333;outline:5px auto -webkit-focus-ring-color;outline-offset:-2px;} +a:hover,a:active{outline:0;} +sub,sup{position:relative;font-size:75%;line-height:0;vertical-align:baseline;} +sup{top:-0.5em;} +sub{bottom:-0.25em;} +img{max-width:100%;vertical-align:middle;border:0;-ms-interpolation-mode:bicubic;} +button,input,select,textarea{margin:0;font-size:100%;vertical-align:middle;} +button,input{*overflow:visible;line-height:normal;} +button::-moz-focus-inner,input::-moz-focus-inner{padding:0;border:0;} +button,input[type="button"],input[type="reset"],input[type="submit"]{cursor:pointer;-webkit-appearance:button;} +input[type="search"]{-webkit-box-sizing:content-box;-moz-box-sizing:content-box;box-sizing:content-box;-webkit-appearance:textfield;} +input[type="search"]::-webkit-search-decoration,input[type="search"]::-webkit-search-cancel-button{-webkit-appearance:none;} +textarea{overflow:auto;vertical-align:top;} +body{margin:0;font-family:"Helvetica Neue",Helvetica,Arial,sans-serif;font-size:13px;line-height:18px;color:#333333;background-color:#ffffff;} +a{color:#0088cc;text-decoration:none;} +a:hover{color:#005580;text-decoration:underline;} +.row{margin-left:-20px;*zoom:1;}.row:before,.row:after{display:table;content:"";} +.row:after{clear:both;} +[class*="span"]{float:left;margin-left:20px;} +.container,.navbar-fixed-top .container,.navbar-fixed-bottom .container{width:940px;} +.span12{width:940px;} +.span11{width:860px;} +.span10{width:780px;} +.span9{width:700px;} +.span8{width:620px;} +.span7{width:540px;} +.span6{width:460px;} +.span5{width:380px;} +.span4{width:300px;} +.span3{width:220px;} +.span2{width:140px;} +.span1{width:60px;} +.offset12{margin-left:980px;} +.offset11{margin-left:900px;} +.offset10{margin-left:820px;} +.offset9{margin-left:740px;} +.offset8{margin-left:660px;} +.offset7{margin-left:580px;} +.offset6{margin-left:500px;} +.offset5{margin-left:420px;} +.offset4{margin-left:340px;} +.offset3{margin-left:260px;} +.offset2{margin-left:180px;} +.offset1{margin-left:100px;} +.row-fluid{width:100%;*zoom:1;}.row-fluid:before,.row-fluid:after{display:table;content:"";} +.row-fluid:after{clear:both;} +.row-fluid [class*="span"]{display:block;width:100%;min-height:28px;-webkit-box-sizing:border-box;-moz-box-sizing:border-box;-ms-box-sizing:border-box;box-sizing:border-box;float:left;margin-left:2.127659574%;*margin-left:2.0744680846382977%;} +.row-fluid [class*="span"]:first-child{margin-left:0;} +.row-fluid .span12{width:99.99999998999999%;*width:99.94680850063828%;} +.row-fluid .span11{width:91.489361693%;*width:91.4361702036383%;} +.row-fluid .span10{width:82.97872339599999%;*width:82.92553190663828%;} +.row-fluid .span9{width:74.468085099%;*width:74.4148936096383%;} +.row-fluid .span8{width:65.95744680199999%;*width:65.90425531263828%;} +.row-fluid .span7{width:57.446808505%;*width:57.3936170156383%;} +.row-fluid .span6{width:48.93617020799999%;*width:48.88297871863829%;} +.row-fluid .span5{width:40.425531911%;*width:40.3723404216383%;} +.row-fluid .span4{width:31.914893614%;*width:31.8617021246383%;} +.row-fluid .span3{width:23.404255317%;*width:23.3510638276383%;} +.row-fluid .span2{width:14.89361702%;*width:14.8404255306383%;} +.row-fluid .span1{width:6.382978723%;*width:6.329787233638298%;} +.container{margin-right:auto;margin-left:auto;*zoom:1;}.container:before,.container:after{display:table;content:"";} +.container:after{clear:both;} +.container-fluid{padding-right:20px;padding-left:20px;*zoom:1;}.container-fluid:before,.container-fluid:after{display:table;content:"";} +.container-fluid:after{clear:both;} +p{margin:0 0 9px;font-family:"Helvetica Neue",Helvetica,Arial,sans-serif;font-size:13px;line-height:18px;}p small{font-size:11px;color:#999999;} +.lead{margin-bottom:18px;font-size:20px;font-weight:200;line-height:27px;} +h1,h2,h3,h4,h5,h6{margin:0;font-family:inherit;font-weight:bold;color:inherit;text-rendering:optimizelegibility;}h1 small,h2 small,h3 small,h4 small,h5 small,h6 small{font-weight:normal;color:#999999;} +h1{font-size:30px;line-height:36px;}h1 small{font-size:18px;} +h2{font-size:24px;line-height:36px;}h2 small{font-size:18px;} +h3{font-size:18px;line-height:27px;}h3 small{font-size:14px;} +h4,h5,h6{line-height:18px;} +h4{font-size:14px;}h4 small{font-size:12px;} +h5{font-size:12px;} +h6{font-size:11px;color:#999999;text-transform:uppercase;} +.page-header{padding-bottom:17px;margin:18px 0;border-bottom:1px solid #eeeeee;} +.page-header h1{line-height:1;} +ul,ol{padding:0;margin:0 0 9px 25px;} +ul ul,ul ol,ol ol,ol ul{margin-bottom:0;} +ul{list-style:disc;} +ol{list-style:decimal;} +li{line-height:18px;} +ul.unstyled,ol.unstyled{margin-left:0;list-style:none;} +dl{margin-bottom:18px;} +dt,dd{line-height:18px;} +dt{font-weight:bold;line-height:17px;} +dd{margin-left:9px;} +.dl-horizontal dt{float:left;width:120px;clear:left;text-align:right;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;} +.dl-horizontal dd{margin-left:130px;} +hr{margin:18px 0;border:0;border-top:1px solid #eeeeee;border-bottom:1px solid #ffffff;} +strong{font-weight:bold;} +em{font-style:italic;} +.muted{color:#999999;} +abbr[title]{cursor:help;border-bottom:1px dotted #ddd;} +abbr.initialism{font-size:90%;text-transform:uppercase;} +blockquote{padding:0 0 0 15px;margin:0 0 18px;border-left:5px solid #eeeeee;}blockquote p{margin-bottom:0;font-size:16px;font-weight:300;line-height:22.5px;} +blockquote small{display:block;line-height:18px;color:#999999;}blockquote small:before{content:'\2014 \00A0';} +blockquote.pull-right{float:right;padding-right:15px;padding-left:0;border-right:5px solid #eeeeee;border-left:0;}blockquote.pull-right p,blockquote.pull-right small{text-align:right;} +q:before,q:after,blockquote:before,blockquote:after{content:"";} +address{display:block;margin-bottom:18px;font-style:normal;line-height:18px;} +small{font-size:100%;} +cite{font-style:normal;} +code,pre{padding:0 3px 2px;font-family:Menlo,Monaco,Consolas,"Courier New",monospace;font-size:12px;color:#333333;-webkit-border-radius:3px;-moz-border-radius:3px;border-radius:3px;} +code{padding:2px 4px;color:#d14;background-color:#f7f7f9;border:1px solid #e1e1e8;} +pre{display:block;padding:8.5px;margin:0 0 9px;font-size:12.025px;line-height:18px;word-break:break-all;word-wrap:break-word;white-space:pre;white-space:pre-wrap;background-color:#f5f5f5;border:1px solid #ccc;border:1px solid rgba(0, 0, 0, 0.15);-webkit-border-radius:4px;-moz-border-radius:4px;border-radius:4px;}pre.prettyprint{margin-bottom:18px;} +pre code{padding:0;color:inherit;background-color:transparent;border:0;} +.pre-scrollable{max-height:340px;overflow-y:scroll;} +.label,.badge{font-size:10.998px;font-weight:bold;line-height:14px;color:#ffffff;vertical-align:baseline;white-space:nowrap;text-shadow:0 -1px 0 rgba(0, 0, 0, 0.25);background-color:#999999;} +.label{padding:1px 4px 2px;-webkit-border-radius:3px;-moz-border-radius:3px;border-radius:3px;} +.badge{padding:1px 9px 2px;-webkit-border-radius:9px;-moz-border-radius:9px;border-radius:9px;} +a.label:hover,a.badge:hover{color:#ffffff;text-decoration:none;cursor:pointer;} +.label-important,.badge-important{background-color:#b94a48;} +.label-important[href],.badge-important[href]{background-color:#953b39;} +.label-warning,.badge-warning{background-color:#f89406;} +.label-warning[href],.badge-warning[href]{background-color:#c67605;} +.label-success,.badge-success{background-color:#468847;} +.label-success[href],.badge-success[href]{background-color:#356635;} +.label-info,.badge-info{background-color:#3a87ad;} +.label-info[href],.badge-info[href]{background-color:#2d6987;} +.label-inverse,.badge-inverse{background-color:#333333;} +.label-inverse[href],.badge-inverse[href]{background-color:#1a1a1a;} +table{max-width:100%;background-color:transparent;border-collapse:collapse;border-spacing:0;} +.table{width:100%;margin-bottom:18px;}.table th,.table td{padding:8px;line-height:18px;text-align:left;vertical-align:top;border-top:1px solid #dddddd;} +.table th{font-weight:bold;} +.table thead th{vertical-align:bottom;} +.table caption+thead tr:first-child th,.table caption+thead tr:first-child td,.table colgroup+thead tr:first-child th,.table colgroup+thead tr:first-child td,.table thead:first-child tr:first-child th,.table thead:first-child tr:first-child td{border-top:0;} +.table tbody+tbody{border-top:2px solid #dddddd;} +.table-condensed th,.table-condensed td{padding:4px 5px;} +.table-bordered{border:1px solid #dddddd;border-collapse:separate;*border-collapse:collapsed;border-left:0;-webkit-border-radius:4px;-moz-border-radius:4px;border-radius:4px;}.table-bordered th,.table-bordered td{border-left:1px solid #dddddd;} +.table-bordered caption+thead tr:first-child th,.table-bordered caption+tbody tr:first-child th,.table-bordered caption+tbody tr:first-child td,.table-bordered colgroup+thead tr:first-child th,.table-bordered colgroup+tbody tr:first-child th,.table-bordered colgroup+tbody tr:first-child td,.table-bordered thead:first-child tr:first-child th,.table-bordered tbody:first-child tr:first-child th,.table-bordered tbody:first-child tr:first-child td{border-top:0;} +.table-bordered thead:first-child tr:first-child th:first-child,.table-bordered tbody:first-child tr:first-child td:first-child{-webkit-border-top-left-radius:4px;border-top-left-radius:4px;-moz-border-radius-topleft:4px;} +.table-bordered thead:first-child tr:first-child th:last-child,.table-bordered tbody:first-child tr:first-child td:last-child{-webkit-border-top-right-radius:4px;border-top-right-radius:4px;-moz-border-radius-topright:4px;} +.table-bordered thead:last-child tr:last-child th:first-child,.table-bordered tbody:last-child tr:last-child td:first-child{-webkit-border-radius:0 0 0 4px;-moz-border-radius:0 0 0 4px;border-radius:0 0 0 4px;-webkit-border-bottom-left-radius:4px;border-bottom-left-radius:4px;-moz-border-radius-bottomleft:4px;} +.table-bordered thead:last-child tr:last-child th:last-child,.table-bordered tbody:last-child tr:last-child td:last-child{-webkit-border-bottom-right-radius:4px;border-bottom-right-radius:4px;-moz-border-radius-bottomright:4px;} +.table-striped tbody tr:nth-child(odd) td,.table-striped tbody tr:nth-child(odd) th{background-color:#f9f9f9;} +.table tbody tr:hover td,.table tbody tr:hover th{background-color:#f5f5f5;} +table .span1{float:none;width:44px;margin-left:0;} +table .span2{float:none;width:124px;margin-left:0;} +table .span3{float:none;width:204px;margin-left:0;} +table .span4{float:none;width:284px;margin-left:0;} +table .span5{float:none;width:364px;margin-left:0;} +table .span6{float:none;width:444px;margin-left:0;} +table .span7{float:none;width:524px;margin-left:0;} +table .span8{float:none;width:604px;margin-left:0;} +table .span9{float:none;width:684px;margin-left:0;} +table .span10{float:none;width:764px;margin-left:0;} +table .span11{float:none;width:844px;margin-left:0;} +table .span12{float:none;width:924px;margin-left:0;} +table .span13{float:none;width:1004px;margin-left:0;} +table .span14{float:none;width:1084px;margin-left:0;} +table .span15{float:none;width:1164px;margin-left:0;} +table .span16{float:none;width:1244px;margin-left:0;} +table .span17{float:none;width:1324px;margin-left:0;} +table .span18{float:none;width:1404px;margin-left:0;} +table .span19{float:none;width:1484px;margin-left:0;} +table .span20{float:none;width:1564px;margin-left:0;} +table .span21{float:none;width:1644px;margin-left:0;} +table .span22{float:none;width:1724px;margin-left:0;} +table .span23{float:none;width:1804px;margin-left:0;} +table .span24{float:none;width:1884px;margin-left:0;} +/* Auto-generated CSS for generated Thrift docs */ +h3, h4 { margin-bottom: 6px; } +div.definition { border: 1px solid #CCC; margin-bottom: 10px; padding: 10px; } +div.extends { margin: -0.5em 0 1em 5em } +td { vertical-align: top; } +table { empty-cells: show; } +code { line-height: 20px; } +.table-bordered th, .table-bordered td { border-bottom: 1px solid #DDDDDD; } diff --git a/public/thrift/wrapper.html b/public/thrift/wrapper.html new file mode 100644 index 0000000..ab26c3a --- /dev/null +++ b/public/thrift/wrapper.html @@ -0,0 +1,16 @@ + + + + + +Thrift module: wrapper +
+

Thrift module: wrapper

+ + + + + +
ModuleServicesData typesConstants
wrapper
+
From a94fe418db929941388959b81a9b09d65e87e35e Mon Sep 17 00:00:00 2001 From: Zoltan Nagy Date: Wed, 31 Jan 2018 11:55:10 +0100 Subject: [PATCH 2/2] [thrift] Loudly say "V1" on generated Thrift documentation Also, remove the fake empty "wrapper" module from index.html --- generate_docs_from_thrift.sh | 15 -- generate_thrift_v1_docs/generate.sh | 44 ++++ generate_thrift_v1_docs/transform.xslt | 23 ++ public/thrift/index.html | 51 ---- public/thrift/v1/index.html | 129 ++++++++++ public/thrift/{ => v1}/style.css | 0 public/thrift/{ => v1}/wrapper.html | 0 public/thrift/v1/zipkinCore.html | 295 +++++++++++++++++++++++ public/thrift/v1/zipkinDependencies.html | 30 +++ 9 files changed, 521 insertions(+), 66 deletions(-) delete mode 100755 generate_docs_from_thrift.sh create mode 100755 generate_thrift_v1_docs/generate.sh create mode 100644 generate_thrift_v1_docs/transform.xslt delete mode 100644 public/thrift/index.html create mode 100644 public/thrift/v1/index.html rename public/thrift/{ => v1}/style.css (100%) rename public/thrift/{ => v1}/wrapper.html (100%) create mode 100644 public/thrift/v1/zipkinCore.html create mode 100644 public/thrift/v1/zipkinDependencies.html diff --git a/generate_docs_from_thrift.sh b/generate_docs_from_thrift.sh deleted file mode 100755 index 5eb6ebb..0000000 --- a/generate_docs_from_thrift.sh +++ /dev/null @@ -1,15 +0,0 @@ -#!/bin/bash - -set -euo pipefail -set -x - -target_root="$(pwd)/public" -cd "$(mktemp -d)" -git clone https://github.com/openzipkin/zipkin-api.git -cd zipkin-api/thrift -rm -fv wrapper.thrift -for source in *.thrift; do - echo "include \"$source\"" >> wrapper.thrift -done -thrift --gen html wrapper.thrift -mv gen-html "$target_root/thrift" diff --git a/generate_thrift_v1_docs/generate.sh b/generate_thrift_v1_docs/generate.sh new file mode 100755 index 0000000..b34e043 --- /dev/null +++ b/generate_thrift_v1_docs/generate.sh @@ -0,0 +1,44 @@ +#!/bin/bash + +set -euo pipefail +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)" +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)" +git clone https://github.com/openzipkin/zipkin-api.git +cd zipkin-api/thrift + +# Generate HTML docs with Thrift +rm -fv wrapper.thrift +for source in *.thrift; do + echo "include \"$source\"" >> wrapper.thrift +done +thrift -r --gen html -I . -out "$target_dir" 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" +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" diff --git a/generate_thrift_v1_docs/transform.xslt b/generate_thrift_v1_docs/transform.xslt new file mode 100644 index 0000000..e8c1c0a --- /dev/null +++ b/generate_thrift_v1_docs/transform.xslt @@ -0,0 +1,23 @@ + + + + + + + + + + + + + Zipkin V1 Thrift models + + +

Zipkin V1 Thrift models

+ + + + + diff --git a/public/thrift/index.html b/public/thrift/index.html deleted file mode 100644 index 0d38ff3..0000000 --- a/public/thrift/index.html +++ /dev/null @@ -1,51 +0,0 @@ - - -All Thrift declarations -
-

All Thrift declarations

- - - - - - - - - - - - - -
ModuleServicesData typesConstants
wrapper
zipkinCoreAnnotation
-AnnotationType
-BinaryAnnotation
-Endpoint
-Span
-		CLIENT_ADDR
-CLIENT_RECV
-CLIENT_RECV_FRAGMENT
-CLIENT_SEND
-CLIENT_SEND_FRAGMENT
-ERROR
-HTTP_HOST
-HTTP_METHOD
-HTTP_PATH
-HTTP_REQUEST_SIZE
-HTTP_RESPONSE_SIZE
-HTTP_STATUS_CODE
-HTTP_URL
-LOCAL_COMPONENT
-MESSAGE_ADDR
-MESSAGE_RECV
-MESSAGE_SEND
-SERVER_ADDR
-SERVER_RECV
-SERVER_RECV_FRAGMENT
-SERVER_SEND
-SERVER_SEND_FRAGMENT
-WIRE_RECV
-WIRE_SEND
-
zipkinDependenciesDependencies
-DependencyLink
-
-
diff --git a/public/thrift/v1/index.html b/public/thrift/v1/index.html new file mode 100644 index 0000000..f7f1e39 --- /dev/null +++ b/public/thrift/v1/index.html @@ -0,0 +1,129 @@ + + + + + + + + + + Zipkin V1 Thrift models + + + + + +
+ +

Zipkin V1 Thrift models

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ModuleServicesData typesConstants
zipkinCore + Annotation
+ AnnotationType
+ + BinaryAnnotation
+ + Endpoint
+ Span
+ + 		CLIENT_ADDR
+ + CLIENT_RECV
+ + CLIENT_RECV_FRAGMENT
+ + CLIENT_SEND
+ + CLIENT_SEND_FRAGMENT
+ + ERROR
+ HTTP_HOST
+ + HTTP_METHOD
+ + HTTP_PATH
+ + HTTP_REQUEST_SIZE
+ + HTTP_RESPONSE_SIZE
+ + HTTP_STATUS_CODE
+ + HTTP_URL
+ LOCAL_COMPONENT
+ + MESSAGE_ADDR
+ + MESSAGE_RECV
+ + MESSAGE_SEND
+ + SERVER_ADDR
+ + SERVER_RECV
+ + SERVER_RECV_FRAGMENT
+ + SERVER_SEND
+ + SERVER_SEND_FRAGMENT
+ + WIRE_RECV
+ + WIRE_SEND
+ +
zipkinDependencies + Dependencies
+ + DependencyLink
+ +
+ +
+ + + + \ No newline at end of file diff --git a/public/thrift/style.css b/public/thrift/v1/style.css similarity index 100% rename from public/thrift/style.css rename to public/thrift/v1/style.css diff --git a/public/thrift/wrapper.html b/public/thrift/v1/wrapper.html similarity index 100% rename from public/thrift/wrapper.html rename to public/thrift/v1/wrapper.html diff --git a/public/thrift/v1/zipkinCore.html b/public/thrift/v1/zipkinCore.html new file mode 100644 index 0000000..7a3e389 --- /dev/null +++ b/public/thrift/v1/zipkinCore.html @@ -0,0 +1,295 @@ + + + + + +Thrift module: zipkinCore +
+

Thrift module: zipkinCore

+ + + + + +
ModuleServicesData typesConstants
zipkinCoreAnnotation
+AnnotationType
+BinaryAnnotation
+Endpoint
+Span
+		CLIENT_ADDR
+CLIENT_RECV
+CLIENT_RECV_FRAGMENT
+CLIENT_SEND
+CLIENT_SEND_FRAGMENT
+ERROR
+HTTP_HOST
+HTTP_METHOD
+HTTP_PATH
+HTTP_REQUEST_SIZE
+HTTP_RESPONSE_SIZE
+HTTP_STATUS_CODE
+HTTP_URL
+LOCAL_COMPONENT
+MESSAGE_ADDR
+MESSAGE_RECV
+MESSAGE_SEND
+SERVER_ADDR
+SERVER_RECV
+SERVER_RECV_FRAGMENT
+SERVER_SEND
+SERVER_SEND_FRAGMENT
+WIRE_RECV
+WIRE_SEND
+
+

Constants

+ +
ConstantTypeValue
CLIENT_SENDstring"cs"
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. +

+If chunking is involved, each chunk could be logged as a separate +CLIENT_SEND_FRAGMENT in the same span. +

+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. +

CLIENT_RECVstring"cr"
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. +

+If chunking is involved, each chunk could be logged as a separate +CLIENT_RECV_FRAGMENT in the same span. +

+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. +

SERVER_SENDstring"ss"
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. +

+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. +

+If chunking is involved, each chunk could be logged as a separate +SERVER_SEND_FRAGMENT in the same span. +

+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. +

SERVER_RECVstring"sr"
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. +

+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. +

+If chunking is involved, each chunk could be logged as a separate +SERVER_RECV_FRAGMENT in the same span. +

+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. +

MESSAGE_SENDstring"ms"
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. +

+Unlike RPC annotations like CLIENT_SEND, messaging spans never share a span +ID. For example, "ms" should always be the parent of "mr". +

+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. +

MESSAGE_RECVstring"mr"
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. +

+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. +

+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. +

WIRE_SENDstring"ws"
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. +
WIRE_RECVstring"wr"
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. +
CLIENT_SEND_FRAGMENTstring"csf"
Optionally logs progress of a (CLIENT_SEND, WIRE_SEND). For example, this +could be one chunk in a chunked request. +
CLIENT_RECV_FRAGMENTstring"crf"
Optionally logs progress of a (CLIENT_RECV, WIRE_RECV). For example, this +could be one chunk in a chunked response. +
SERVER_SEND_FRAGMENTstring"ssf"
Optionally logs progress of a (SERVER_SEND, WIRE_SEND). For example, this +could be one chunk in a chunked response. +
SERVER_RECV_FRAGMENTstring"srf"
Optionally logs progress of a (SERVER_RECV, WIRE_RECV). For example, this +could be one chunk in a chunked request. +
HTTP_HOSTstring"http.host"
The domain portion of the URL or host header. Ex. "mybucket.s3.amazonaws.com" +

+Used to filter by host as opposed to ip address. +

HTTP_METHODstring"http.method"
The HTTP method, or verb, such as "GET" or "POST". +

+Used to filter against an http route. +

HTTP_PATHstring"http.path"
The absolute http path, without any query parameters. Ex. "/objects/abcd-ff" +

+Used to filter against an http route, portably with zipkin v1. +

+In zipkin v1, only equals filters are supported. 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. This does not reduce cardinality to a HTTP single route. +For example, it is common to express a route as an http URI template like +"/resource/{resource_id}". In systems where only equals queries are available, searching for +http/path=/resource won't match if the actual request was /resource/abcd-ff. +

+Historical note: This was commonly expressed as "http.uri" in zipkin, even though it was most +often just a path. +

HTTP_URLstring"http.url"
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..." +

+Combined with HTTP_METHOD, you can understand the fully-qualified request line. +

+This is optional as it may include private data or be of considerable length. +

HTTP_STATUS_CODEstring"http.status_code"
The HTTP status code, when not in 2xx range. Ex. "503" +

+Used to filter for error status. +

HTTP_REQUEST_SIZEstring"http.request.size"
The size of the non-empty HTTP request body, in bytes. Ex. "16384" +

+Large uploads can exceed limits or contribute directly to latency. +

HTTP_RESPONSE_SIZEstring"http.response.size"
The size of the non-empty HTTP response body, in bytes. Ex. "16384" +

+Large downloads can exceed limits or contribute directly to latency. +

LOCAL_COMPONENTstring"lc"
The value of "lc" is the component or namespace of a local span. +

+BinaryAnnotation.host adds service context needed to support queries. +

+Local Component("lc") supports three key features: flagging, query by +service and filtering Span.name by namespace. +

+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. +

+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. +

+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" +

ERRORstring"error"
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. +

+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. +

+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. +

+Note that RPC spans often include both client and server hosts: It is +possible that only one side perceived the error. +

CLIENT_ADDRstring"ca"
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. +
SERVER_ADDRstring"sa"
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. +
MESSAGE_ADDRstring"ma"
Indicates the remote address of a messaging span, usually the broker. +

Enumerations

+

Enumeration: AnnotationType

+A subset of thrift base types, except BYTES. +

+ + + + + + + +
BOOL0 +Set to 0x01 when key is CLIENT_ADDR or SERVER_ADDR +
BYTES1 +No encoding, or type is unknown. +
I162 +
I323 +
I644 +
DOUBLE5 +
STRING6 +the only type zipkin v1 supports search against. +
+

Data structures

+

Struct: Endpoint

+ + + + + +
KeyFieldTypeDescriptionRequirednessDefault value
1ipv4i32IPv4 host address packed into 4 bytes.

Ex for the ip 1.2.3.4, it would be (1 << 24) | (2 << 16) | (3 << 8) | 4
default
2porti16IPv4 port or 0, if unknown.

Note: this is to be treated as an unsigned integer, so watch for negatives.
default
3service_namestringClassifier 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.
default
4ipv6binaryIPv6 host address packed into 16 bytes. Ex Inet6Address.getBytes()
optional

Indicates the network context of a service recording an annotation with two +exceptions. +

+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. +

Struct: Annotation

+ + + + +
KeyFieldTypeDescriptionRequirednessDefault value
1timestampi64Microseconds from epoch.

This value should use the most precise value possible. For example,
gettimeofday or multiplying currentTimeMillis by 1000.
default
2valuestringUsually a short tag indicating an event, like "sr" or "finagle.retry".
default
3hostEndpointThe host that recorded the value, primarily for query by service name.
optional

Associates an event that explains latency with a timestamp. +

+Unlike log statements, annotations are often codes: for example "sr". +

Struct: BinaryAnnotation

+ + + + + +
KeyFieldTypeDescriptionRequirednessDefault value
1keystringName used to lookup spans, such as "http.path" or "finagle.version".
default
2valuebinarySerialized thrift bytes, in TBinaryProtocol format.

For legacy reasons, byte order is big-endian. See THRIFT-3217.
default
3annotation_typeAnnotationTypeThe thrift type of value, most often STRING.

annotation_type shouldn't vary for the same key.
default
4hostEndpointThe 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.
optional

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. +

+Binary annotations of type STRING are always queryable, though more a +historical implementation detail than a structural concern. +

+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. +

Struct: Span

+ + + + + + + + + + + +
KeyFieldTypeDescriptionRequirednessDefault value
1trace_idi64Unique 8-byte identifier for a trace, set on all spans within it.
default
3namestringSpan name in lowercase, rpc method for example. Conventionally, when the
span name isn't known, name = "unknown".
default
4idi64Unique 8-byte identifier of this span within a trace. A span is uniquely
identified in storage by (trace_id, id).
default
5parent_idi64The parent's Span.id; absent if this the root span in a trace.
optional
6annotationslist<Annotation>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.
default
8binary_annotationslist<BinaryAnnotation>Tags a span with context, usually to support query or aggregation. For
example, a binary annotation key could be "http.path".
default
9debugboolTrue is a request to store this span even if it overrides sampling policy.
optional0
10timestampi64Epoch 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
optional
11durationi64Measurement 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.
optional
12trace_id_highi64Optional unique 8-byte additional identifier for a trace. If non zero, this
means the trace uses 128 bit traceIds instead of 64 bit.
optional

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. +

+The root span is where parent_id = Nil; it usually has the longest duration +in the trace. +

+Span identifiers are packed into i64s, but should be treated opaquely. +String encoding is fixed-width lower-hex, to avoid signed interpretation. +

diff --git a/public/thrift/v1/zipkinDependencies.html b/public/thrift/v1/zipkinDependencies.html new file mode 100644 index 0000000..ae9588f --- /dev/null +++ b/public/thrift/v1/zipkinDependencies.html @@ -0,0 +1,30 @@ + + + + + +Thrift module: zipkinDependencies +
+

Thrift module: zipkinDependencies

+ + + + + +
ModuleServicesData typesConstants
zipkinDependenciesDependencies
+DependencyLink
+
+

Data structures

+
+ + + + + +
KeyFieldTypeDescriptionRequirednessDefault value
1parentstringparent service name (caller)
default
2childstringchild service name (callee)
default
4callCounti64total traced calls made from parent to child
default
5errorCounti64how many calls are known to be errors
default

Struct: Dependencies

+ + + + +
KeyFieldTypeDescriptionRequirednessDefault value
1start_tsi64milliseconds from epoch
default
2end_tsi64milliseconds from epoch
default
3linkslist<DependencyLink>default