Author: buildbot
Date: Sat Feb 11 16:47:44 2017
New Revision: 1006557
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/using-openzipkin-brave.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/cxf/content/docs/using-openzipkin-brave.html
==============================================================================
--- websites/production/cxf/content/docs/using-openzipkin-brave.html (original)
+++ websites/production/cxf/content/docs/using-openzipkin-brave.html Sat Feb 11
16:47:44 2017
@@ -33,6 +33,7 @@
<script src='/resources/highlighter/scripts/shCore.js'></script>
<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
+<script src='/resources/highlighter/scripts/shBrushXml.js'></script>
<script>
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -117,14 +118,14 @@ Apache CXF -- Using OpenZipkin Brave
<!-- Content -->
<div class="wiki-content">
<div id="ConfluenceContent"><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1486439239441 {padding: 0px;}
-div.rbtoc1486439239441 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1486439239441 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1486831628190 {padding: 0px;}
+div.rbtoc1486831628190 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1486831628190 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1486439239441">
+/*]]>*/</style></p><div class="toc-macro rbtoc1486831628190">
<ul class="toc-indentation"><li><a shape="rect"
href="#UsingOpenZipkinBrave-Overview">Overview</a></li><li><a shape="rect"
href="#UsingOpenZipkinBrave-DistributedTracinginApacheCXFusingOpenZipkinBrave">Distributed
Tracing in Apache CXF using OpenZipkin Brave</a></li><li><a shape="rect"
href="#UsingOpenZipkinBrave-configuringclientConfiguringClient">Configuring
Client</a></li><li><a shape="rect"
href="#UsingOpenZipkinBrave-configuringserverConfiguringServer">Configuring
Server</a></li><li><a shape="rect"
href="#UsingOpenZipkinBrave-DistributedTracingInAction:UsageScenarios">Distributed
Tracing In Action: Usage Scenarios</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#UsingOpenZipkinBrave-Example#1:ClientandServerwithdefaultdistributedtracingconfigured">Example
#1: Client and Server with default distributed tracing
configured</a></li><li><a shape="rect"
href="#UsingOpenZipkinBrave-Example#2:ClientandServerwithnestedtrace">Example
#2: Client and Server with nested trace</a></li><li><a shape="rect"
href="#UsingOpenZipkinBrave-Example#3:ClientandServertracewithannotations">Example
#3: Client and Server trace with annotations</a></li><li><a shape="rect"
href="#UsingOpenZipkinBrave-Example#4:ClientandServerwithbinaryannotations(key/value)">Example
#4: Client and Server with binary annotations (key/value)</a></li><li><a
shape="rect"
href="#UsingOpenZipkinBrave-Example#5:ClientandServerwithparalleltrace(involvingthreadpools)">Example
#5: Client and Server with parallel trace (involving thread
pools)</a></li><li><a shape="rect"
href="#UsingOpenZipkinBrave-Example#6:ClientandServerwithasynchronousJAX-
RSservice(server-side)">Example #6: Client and Server with asynchronous JAX-RS
service (server-side)</a></li><li><a shape="rect"
href="#UsingOpenZipkinBrave-Example#7:ClientandServerwithasynchronousinvocation(client-side)">Example
#7: Client and Server with asynchronous invocation (client-side)</a></li></ul>
-</li><li><a shape="rect"
href="#UsingOpenZipkinBrave-DistributedTracingwithOpenZipkinBraveandJAX-WSsupport">Distributed
Tracing with OpenZipkin Brave and JAX-WS support</a></li><li><a shape="rect"
href="#UsingOpenZipkinBrave-Migratingfrombrave-cxf3">Migrating from
brave-cxf3</a></li></ul>
+</li><li><a shape="rect"
href="#UsingOpenZipkinBrave-DistributedTracingwithOpenZipkinBraveandJAX-WSsupport">Distributed
Tracing with OpenZipkin Brave and JAX-WS support</a></li><li><a shape="rect"
href="#UsingOpenZipkinBrave-DistributedTracingwithOpenZipkinBraveandOSGi">Distributed
Tracing with OpenZipkin Brave and OSGi</a></li><li><a shape="rect"
href="#UsingOpenZipkinBrave-Migratingfrombrave-cxf3">Migrating from
brave-cxf3</a></li></ul>
</div><h1 id="UsingOpenZipkinBrave-Overview">Overview</h1><p><a shape="rect"
class="external-link" href="https://github.com/openzipkin/brave";
rel="nofollow">OpenZipkin Brave</a> is a distributed tracing implementation
compatible with <a shape="rect" class="external-link" href="http://zipkin.io/";
rel="nofollow">Twitter Zipkin</a> backend services, written in Java. For quite
a while <a shape="rect" class="external-link"
href="https://github.com/openzipkin/brave"; rel="nofollow">OpenZipkin Brave</a>
offers a dedicated module to integrate with Apache CXF framework, namely <a
shape="rect" class="external-link"
href="https://github.com/openzipkin/brave/tree/master/brave-cxf3";
rel="nofollow">brave-cxf3</a>. However, lately the discussion <a shape="rect"
class="external-link" href="https://github.com/openzipkin/brave/issues/313";
rel="nofollow">had been initiated</a> to make this integration a part of Apache
CXF codebase so the CXF team is going to be responsible for maintaining it. As
such,
it is going to be available in upcoming <strong>3.2.0</strong> release under
<strong>cxf-integration-tracing-brave</strong> module, with both client side
and server side supported. This section gives a complete overview on how
distributed tracing using <a shape="rect" class="external-link"
href="https://github.com/openzipkin/brave"; rel="nofollow">OpenZipkin Brave</a>
could be integrated into JAX-RS / JAX-WS applications built on top of Apache
CXF.</p><p><a shape="rect" class="external-link"
href="https://github.com/openzipkin/brave"; rel="nofollow">OpenZipkin Brave</a>
is inspired by the <a shape="rect" class="external-link"
href="http://zipkin.io/"; rel="nofollow">Twitter Zipkin</a> and <a shape="rect"
class="external-link" href="http://research.google.com/pubs/pub36356.html";
rel="nofollow">Dapper, a Large-Scale Distributed Systems Tracing
Infrastructure</a> paper and is a full-fledged distributed tracing framework.
The section <a shape="rect" href="using-apache-htrace.html
">dedicated to Apache HTrace </a>has pretty good introduction into distributed
tracing basics. However, there are a few key differences between <a
shape="rect" class="external-link"
href="http://htrace.incubator.apache.org/index.html";>Apache HTrace</a> and <a
shape="rect" class="external-link" href="https://github.com/openzipkin/brave";
rel="nofollow">OpenZipkin Brave</a>. In <a shape="rect" class="external-link"
href="https://github.com/openzipkin/brave"; rel="nofollow">Brave</a> every
<strong>Span</strong> is associated with 128 or 64-bit long <strong>Trace
ID</strong>, which logically groups the <strong>spans</strong> related to the
same distributed unit of work. Within the process <strong>span</strong>s are
collected by <strong>reporters</strong> (it could be a console, local file,
data store, ...). <a shape="rect" class="external-link"
href="https://github.com/openzipkin/brave"; rel="nofollow">OpenZipkin Brave</a>
provides span reporters for <a shape="rect" class="external-link" h
ref="http://zipkin.io/"; rel="nofollow">Twitter Zipkin</a> and
<strong>java.util.logging</strong> loggers.</p><p>Under the hood
<strong>spans</strong> are attached to their threads (in general, thread which
created the <strong>span</strong> should close it), the same technique employed
by other distributed tracing implementations. However, what is unique is that
<a shape="rect" class="external-link"
href="https://github.com/openzipkin/brave"; rel="nofollow">OpenZipkin Brave</a>
distinguishes three different types of tracers:</p><ul style="list-style-type:
square;"><li>server tracer
(<strong>com.github.kristofa.brave.ServerTracer</strong>)</li><li>client tracer
(<strong>com.github.kristofa.brave.ClientTracer</strong>)</li><li>local tracer
(<strong>com.github.kristofa.brave</strong>.<strong>LocalTracer</strong>)</li></ul><p><a
shape="rect" href="http://cxf.apache.org/";>Apache CXF</a> integration uses
<strong>client tracer</strong> to instantiate spans on client side (providers
and inter
ceptors) to demarcate send / receive cycle, <strong>server tracer</strong> on
the server side (providers and interceptors) to demarcate receive / send cycle,
while using <strong>local tracer</strong> for any spans instantiated within a
process.</p><h1
id="UsingOpenZipkinBrave-DistributedTracinginApacheCXFusingOpenZipkinBrave">Distributed
Tracing in Apache CXF using OpenZipkin Brave</h1><p>The current integration of
distributed tracing in <a shape="rect" href="http://cxf.apache.org/";>Apache
CXF</a> supports <a shape="rect" class="external-link"
href="https://github.com/openzipkin/brave"; rel="nofollow">OpenZipkin Brave</a>
(<strong>3.16+</strong> release branch) in JAX-RS 2.x+ and JAX-WS applications,
including the applications deploying in <a shape="rect" class="external-link"
href="https://www.osgi.org/"; rel="nofollow">OSGi</a> containers. From
high-level perspective, JAX-RS 2.x+ integration consists of three main
parts:</p><ul><li><strong>TracerContext</strong> (injectabl
e through <strong>@Context</strong>
annotation)</li><li><strong>BraveProvider</strong> (server-side JAX-RS
provider) and <strong>BraveClientProvider</strong> (client-side JAX-RS
provider)</li><li><strong>BraveFeature</strong> (server-side JAX-RS
feature to simplify <a shape="rect" class="external-link"
href="https://github.com/openzipkin/brave"; rel="nofollow">OpenZipkin Brave</a>
configuration and integration)</li></ul><p>Similarly, from high-level
perspective, JAX-WS integration includes:</p><ul style="list-style-type:
square;"><li><strong>BraveStartInterceptor</strong> /
<strong>BraveStopInterceptor</strong> / <strong>BraveFeature </strong><a
shape="rect" href="http://cxf.apache.org/";>Apache CXF</a> feature (server-side
JAX-WS support)</li><li><strong>BraveClientStartInterceptor</strong> /
<strong>BraveClientStopInterceptor</strong> /
<strong>BraveClientFeature </strong><a shape="rect"
href="http://cxf.apache.org/";>Apache CXF</a> feature (client-side JAX-W
S support)</li></ul><p><a shape="rect" href="http://cxf.apache.org/";>Apache
CXF</a> uses HTTP headers to hand off tracing context from the client to the
service and from the service to service. Those headers are used internally by
<a shape="rect" class="external-link"
href="https://github.com/openzipkin/brave"; rel="nofollow">OpenZipkin Brave</a>
and are not configurable at the moment. The header names are declared in
the <strong>BraveHttpHeaders</strong> class and at the moment
include:</p><ul style="list-style-type:
square;"><li><strong>X-B3-TraceId</strong>: 128 or 64-bit trace
ID</li><li><strong>X-B3-SpanId</strong>: 64-bit span
ID</li><li><strong>X-B3-ParentSpanId</strong>: 64-bit parent span
ID</li><li><p><strong>X-B3-Sampled</strong>: "1" means report this span to the
tracing system, "0" means do not</p></li></ul><p>By default,
<strong>BraveClientProvider</strong> will try to pass the currently active
<strong>span</strong> through HTTP headers on each service invocation.
If there is no active spans, the new span will be created and passed through
HTTP headers on per-invocation basis. Essentially, for JAX-RS applications just
registering <strong>BraveClientProvider</strong> on the client and
<strong>BraveProvider</strong> on the server is enough to have tracing context
to be properly passed everywhere. The only configuration part which is
necessary are <strong>span reports(s)</strong> and
<strong>sampler</strong>(s).</p><p>It is also worth to mention the way <a
shape="rect" href="http://cxf.apache.org/";>Apache CXF</a> attaches the
description to <strong>spans</strong>. With regards to the client integration,
the description becomes a full URL being invoked prefixed by HTTP method, for
example: <strong>GET </strong><a shape="rect" class="external-link"
href="http://localhost:8282/books";
rel="nofollow"><strong>http://localhost:8282</strong>/books</a>. On the server
side integration, the description becomes a relative JAX-RS resource path
prefixed by HT
TP method, f.e.: <strong>GET books, POST book/123</strong></p><h1
id="UsingOpenZipkinBrave-configuringclientConfiguringClient"><span
class="confluence-anchor-link"
id="UsingOpenZipkinBrave-configuringclient"></span>Configuring
Client</h1><p>There are a couple of ways the JAX-RS client could be configured,
depending on the client implementation. <a shape="rect"
href="http://cxf.apache.org/";>Apache CXF</a> provides its own
<strong>WebClient</strong> which could be configured just like that (in future
versions, there would be a simpler ways to do that using client specific
features):</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">// Configure the spans transport sender
final Sender sender = ...;
@@ -352,7 +353,92 @@ public Collection<Book> getBooks()
.accept(MediaType.APPLICATION_JSON)
.async()
.get();</pre>
-</div></div><p>In this respect, there is no difference from the caller
prospective however a bit more work is going under the hood to transfer the
active tracing span from JAX-RS client request filter to client response filter
as in general those are executed in different threads (similarly to server-side
asynchronous JAX-RS resource invocation). The actual invocation of the request
by the client (with service name <strong>tracer-<span class="label
label-default service-filter-label
service-tag-filtered">client</span></strong>) and consequent invocation of the
service on the server side (service name<strong> tracer-<span class="label
label-default service-filter-label">server</span></strong>) is going to
generate the following sample traces:</p><p><span
class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image" width="900"
src="using-openzipkin-brave.data/image2017-2-6%2021:6:56.png"></span></p><h1
id="UsingOpenZipkinBrave-Distrib
utedTracingwithOpenZipkinBraveandJAX-WSsupport">Distributed Tracing with
OpenZipkin Brave and JAX-WS support</h1><p>// TODO</p><h1
id="UsingOpenZipkinBrave-Migratingfrombrave-cxf3">Migrating from
brave-cxf3</h1><p>// TODO</p></div>
+</div></div><p>In this respect, there is no difference from the caller
prospective however a bit more work is going under the hood to transfer the
active tracing span from JAX-RS client request filter to client response filter
as in general those are executed in different threads (similarly to server-side
asynchronous JAX-RS resource invocation). The actual invocation of the request
by the client (with service name <strong>tracer-<span class="label
label-default service-filter-label
service-tag-filtered">client</span></strong>) and consequent invocation of the
service on the server side (service name<strong> tracer-<span class="label
label-default service-filter-label">server</span></strong>) is going to
generate the following sample traces:</p><p><span
class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image" width="900"
src="using-openzipkin-brave.data/image2017-2-6%2021:6:56.png"></span></p><h1
id="UsingOpenZipkinBrave-Distrib
utedTracingwithOpenZipkinBraveandJAX-WSsupport">Distributed Tracing with
OpenZipkin Brave and JAX-WS support</h1><p>Distributed tracing in the <a
shape="rect" href="http://cxf.apache.org/";>Apache CXF</a> is build primarily
around JAX-RS 2.x implementation. However, JAX-WS is also supported but it
requires to write some boiler-plate code and use <a shape="rect"
class="external-link" href="https://github.com/openzipkin/brave";
rel="nofollow">OpenZipkin Brave</a> API directly (the JAX-WS integration is
going to be enhanced in the future). Essentially, from the server-side
prospective the in/out interceptors, <strong>BraveStartInterceptor</strong> and
<strong>BraveStopInterceptor </strong>respectively, should be configured as
part of interceptor chains, either manually or using
<strong>BraveFeature</strong>. For example:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">// Configure the spans transport sender
+final Sender sender = ...;
+
+/**
+ * For example:
+ *
+ * final Sender sender = LibthriftSender.create("localhost");;
+ */
+
+final Brave brave = new Brave.Builder("tracer")
+ .reporter(AsyncReporter.builder(sender).build())
+ .traceSampler(Sampler.ALWAYS_SAMPLE) /* or any other Sampler */
+ .build();
+
+final JaxWsServerFactoryBean sf = new JaxWsServerFactoryBean();
+...
+sf.getFeatures().add(new BraveFeature(brave));
+...
+sf.create();
+
+</pre>
+</div></div><p>Similarly to the server-side, client-side needs own set of
out/in interceptors, <strong>BraveClientStartInterceptor</strong> and
<strong>BraveClientStopInterceptor</strong> (or
<strong>BraveClientFeature</strong>). Please notice the difference from
server-side:  <strong>BraveClientStartInterceptor</strong> becomes
out-interceptor while <strong>BraveClientStopInterceptor</strong> becomes
in-interceptor. For example:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">// Configure the spans transport sender
+final Sender sender = ...;
+
+/**
+ * For example:
+ *
+ * final Sender sender = LibthriftSender.create("localhost");;
+ */
+
+final Brave brave = new Brave.Builder("tracer")
+ .reporter(AsyncReporter.builder(sender).build())
+ .traceSampler(Sampler.ALWAYS_SAMPLE) /* or any other Sampler */
+ .build();
+
+final JaxWsProxyFactoryBean sf = new JaxWsProxyFactoryBean();
+...
+sf.getFeatures().add(new BraveClientFeature(brave));
+...
+sf.create();
+
+</pre>
+</div></div><h1
id="UsingOpenZipkinBrave-DistributedTracingwithOpenZipkinBraveandOSGi">Distributed
Tracing with OpenZipkin Brave and OSGi</h1><p><a shape="rect"
class="external-link" href="https://github.com/openzipkin/brave";
rel="nofollow">OpenZipkin Brave</a> could be deployed into
<strong>OSGi</strong> container and as such, distributed tracing integration is
fully available for <a shape="rect" href="http://cxf.apache.org/";>Apache
CXF</a> services running inside the container. For a complete example please
take a look on <a shape="rect" class="external-link"
href="https://github.com/apache/cxf/blob/180d0fcc5e0d061f339e1a3cb32ec53a3ab32b97/distribution/src/main/release/samples/jaxws_tracing_brave_osgi/README.txt";
rel="nofollow">jax_ws_tracing_brave_osgi</a> sample project, but here is the
typical <strong>OSGi</strong>  Blueprint snippet:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><?xml version="1.0" encoding="UTF-8"?>
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xmlns:cxf="http://cxf.apache.org/blueprint/core";
+ xmlns:jaxws="http://cxf.apache.org/blueprint/jaxws";
+
+ xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0
http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
+ http://cxf.apache.org/blueprint/core
http://cxf.apache.org/schemas/blueprint/core.xsd
+ http://cxf.apache.org/blueprint/jaxws
http://cxf.apache.org/schemas/blueprint/jaxws.xsd">
+
+ <!-- CXF BraveFeature -->
+ <bean id="braveFeature"
class="org.apache.cxf.tracing.brave.BraveFeature">
+ <argument index="0" ref="brave" />
+ </bean>
+
+ <cxf:bus>
+ <cxf:features>
+ <cxf:logging />
+ </cxf:features>
+ </cxf:bus>
+
+ <bean id="catalogServiceImpl"
class="demo.jaxws.tracing.server.impl.CatalogServiceImpl">
+ <argument index="0" ref="brave" />
+ </bean>
+
+ <bean id="braveBuilder"
class="com.github.kristofa.brave.Brave.Builder">
+ <argument index="0" value="catalog-service" />
+ </bean>
+
+ <bean id="brave" factory-ref="braveBuilder" factory-method="build" />
+
+ <jaxws:endpoint
+ implementor="#catalogServiceImpl"
+ address="/catalog"
+
implementorClass="demo.jaxws.tracing.server.impl.CatalogServiceImpl">
+ <jaxws:features>
+ <ref component-id="braveFeature" />
+ </jaxws:features>
+ </jaxws:endpoint>
+</blueprint></pre>
+</div></div><p> </p><h1
id="UsingOpenZipkinBrave-Migratingfrombrave-cxf3">Migrating from
brave-cxf3</h1><p>// TODO</p></div>
</div>
<!-- Content -->
</td>
