Author: buildbot
Date: Fri Sep 15 02:42:54 2023
New Revision: 1084174
Log:
Production update by buildbot for cxf
Added:
websites/production/cxf/content/docs/using-micrometer-observation.data/image-2023-9-14_21-45-17.png
(with props)
websites/production/cxf/content/docs/using-micrometer-observation.data/image-2023-9-14_22-15-19.png
(with props)
websites/production/cxf/content/docs/using-micrometer-observation.data/image-2023-9-14_22-17-50.png
(with props)
websites/production/cxf/content/docs/using-micrometer-observation.data/image-2023-9-14_22-19-42.png
(with props)
websites/production/cxf/content/docs/using-micrometer-observation.data/image-2023-9-14_22-22-5.png
(with props)
websites/production/cxf/content/docs/using-micrometer-observation.data/image-2023-9-14_22-24-11.png
(with props)
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/using-micrometer-observation.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Added:
websites/production/cxf/content/docs/using-micrometer-observation.data/image-2023-9-14_21-45-17.png
==============================================================================
Binary file - no diff available.
Propchange:
websites/production/cxf/content/docs/using-micrometer-observation.data/image-2023-9-14_21-45-17.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added:
websites/production/cxf/content/docs/using-micrometer-observation.data/image-2023-9-14_22-15-19.png
==============================================================================
Binary file - no diff available.
Propchange:
websites/production/cxf/content/docs/using-micrometer-observation.data/image-2023-9-14_22-15-19.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added:
websites/production/cxf/content/docs/using-micrometer-observation.data/image-2023-9-14_22-17-50.png
==============================================================================
Binary file - no diff available.
Propchange:
websites/production/cxf/content/docs/using-micrometer-observation.data/image-2023-9-14_22-17-50.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added:
websites/production/cxf/content/docs/using-micrometer-observation.data/image-2023-9-14_22-19-42.png
==============================================================================
Binary file - no diff available.
Propchange:
websites/production/cxf/content/docs/using-micrometer-observation.data/image-2023-9-14_22-19-42.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added:
websites/production/cxf/content/docs/using-micrometer-observation.data/image-2023-9-14_22-22-5.png
==============================================================================
Binary file - no diff available.
Propchange:
websites/production/cxf/content/docs/using-micrometer-observation.data/image-2023-9-14_22-22-5.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added:
websites/production/cxf/content/docs/using-micrometer-observation.data/image-2023-9-14_22-24-11.png
==============================================================================
Binary file - no diff available.
Propchange:
websites/production/cxf/content/docs/using-micrometer-observation.data/image-2023-9-14_22-24-11.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: websites/production/cxf/content/docs/using-micrometer-observation.html
==============================================================================
--- websites/production/cxf/content/docs/using-micrometer-observation.html
(original)
+++ websites/production/cxf/content/docs/using-micrometer-observation.html Fri
Sep 15 02:42:54 2023
@@ -32,6 +32,7 @@
<link type="text/css" rel="stylesheet"
href="/resources/highlighter/styles/shThemeCXF.css">
<script src='/resources/highlighter/scripts/shCore.js'></script>
+<script src='/resources/highlighter/scripts/shBrushBash.js'></script>
<script src='/resources/highlighter/scripts/shBrushJava.js'></script>
<script>
SyntaxHighlighter.defaults['toolbar'] = false;
@@ -107,15 +108,15 @@ Apache CXF -- Using Micrometer Observati
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"><h1
id="UsingMicrometerObservation-/*<![CDATA[*/div.rbtoc1694742169433{padding:0px;}div.rbtoc1694742169433ul{margin-left:0px;}div.rbtoc1694742169433li{margin-left:0px;padding-left:0px;}/*]]>*/#UsingMicrometerObservation-Overview#UsingMicrometerObservation-Overvie"><style
type="text/css">/*<![CDATA[*/
-div.rbtoc1694742169433 {padding: 0px;}
-div.rbtoc1694742169433 ul {margin-left: 0px;}
-div.rbtoc1694742169433 li {margin-left: 0px;padding-left: 0px;}
+<div id="ConfluenceContent"><h1
id="UsingMicrometerObservation-/*<![CDATA[*/div.rbtoc1694745770444{padding:0px;}div.rbtoc1694745770444ul{margin-left:0px;}div.rbtoc1694745770444li{margin-left:0px;padding-left:0px;}/*]]>*/#UsingMicrometerObservation-Overview#UsingMicrometerObservation-Overvie"><style
type="text/css">/*<![CDATA[*/
+div.rbtoc1694745770444 {padding: 0px;}
+div.rbtoc1694745770444 ul {margin-left: 0px;}
+div.rbtoc1694745770444 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></h1><div class="toc-macro rbtoc1694742169433">
+/*]]>*/</style></h1><div class="toc-macro rbtoc1694745770444">
<ul class="toc-indentation"><li><a shape="rect"
href="#UsingMicrometerObservation-"></a></li><li><a shape="rect"
href="#UsingMicrometerObservation-Overview">Overview</a></li><li><a
shape="rect"
href="#UsingMicrometerObservation-DistributedTracinginApacheCXFusingMicrometerObservation">Distributed
Tracing in Apache CXF using Micrometer Observation</a></li><li><a shape="rect"
href="#UsingMicrometerObservation-ConfiguringClient">Configuring
Client</a></li><li><a shape="rect"
href="#UsingMicrometerObservation-ConfiguringServer">Configuring
Server</a></li><li><a shape="rect"
href="#UsingMicrometerObservation-DistributedTracingInAction:UsageScenarios">Distributed
Tracing In Action: Usage Scenarios</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#UsingMicrometerObservation-Example#1:ClientandServerwithdefaultdistributedtracingconfigured">Example
#1: Client and Server with default distributed tracing
configured</a></li><li><a shape="rect"
href="#UsingMicrometerObservation-Example#2:ClientandServerwithnestedtrace">Example
#2: Client and Server with nested trace</a></li><li><a shape="rect"
href="#UsingMicrometerObservation-Example#3:ClientandServertracewithannotations">Example
#3: Client and Server trace with annotations</a></li><li><a shape="rect"
href="#UsingMicrometerObservation-Example#4:ClientandServerwithbinaryannotations(key/value)">Example
#4: Client and Server with binary annotations (key/value)</a></li><li><a
shape="rect"
href="#UsingMicrometerObservation-Example#5:ClientandServerwithparalleltrace(involvingthreadpools)">Example
#5: Client and Server with parallel trace (involving thread
pools)</a></li><li><a shape="rect" href="#UsingMicrometerObservation-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="#UsingMicrometerObservation-Example#7:ClientandServerwithasynchronousinvocation(client-side)">Example
#7: Client and Server with asynchronous invocation (client-side)</a></li></ul>
-</li><li><a shape="rect"
href="#UsingMicrometerObservation-DistributedTracingwithMicrometerObservationandJAX-WSsupport">Distributed
Tracing with Micrometer Observation and JAX-WS support</a></li><li><a
shape="rect"
href="#UsingMicrometerObservation-AccessingMicrometerObservationAPIs">Accessing
Micrometer Observation APIs</a></li><li><a shape="rect"
href="#UsingMicrometerObservation-Usingnon-JAX-RSclients">Using non-JAX-RS
clients</a></li></ul>
+</li><li><a shape="rect"
href="#UsingMicrometerObservation-DistributedTracingwithMicrometerObservationandJAX-WSsupport">Distributed
Tracing with Micrometer Observation and JAX-WS support</a></li><li><a
shape="rect"
href="#UsingMicrometerObservation-AccessingMicrometerObservationAPIs">Accessing
Micrometer Observation APIs</a></li><li><a shape="rect"
href="#UsingMicrometerObservation-Usingnon-JAX-RSclients">Using non-JAX-RS
clients</a></li><li><a shape="rect"
href="#UsingMicrometerObservation-Samples">Samples</a></li></ul>
</div><h1 id="UsingMicrometerObservation-Overview">Overview</h1><p><a
shape="rect" class="external-link" href="https://micrometer.io/";
rel="nofollow">Micrometer</a> is a metrics instrumentation library for
JVM-based applications that Apache CXF <a shape="rect"
href="https://cwiki.apache.org/confluence/display/CXF20DOC/Micrometer";>provides
the support for</a>. Starting from <a shape="rect" class="external-link"
href="https://micrometer.io/"; rel="nofollow">Micrometer</a>
<strong>1.10</strong>, <a shape="rect" class="external-link"
href="https://micrometer.io/"; rel="nofollow">Micrometer</a> provides the <a
shape="rect" class="external-link"
href="https://micrometer.io/docs/observation"; rel="nofollow">Observation
API</a> and a plugin mechanism that allows to add capabilities including the
tracing features. Starting from <strong>4.0.3 </strong>release, the Apache CXF
fully supports integration (through <strong>cxf-integration-tracing-micrometer
</strong>module) with <a shape="rect" class
="external-link" href="https://micrometer.io/docs/tracing";
rel="nofollow">Micrometer Tracing</a> distributed tracing capabilities using <a
shape="rect" class="external-link"
href="https://micrometer.io/docs/observation"; rel="nofollow">Micrometer
Observation APIs</a>.</p><p>The section <a shape="rect"
href="https://cwiki.apache.org/confluence/display/CXF20DOC/Using+Apache+HTrace";>dedicated
to Apache HTrace </a>has pretty good introduction into distributed tracing,
however <a shape="rect" class="external-link"
href="https://micrometer.io/docs/observation"; rel="nofollow">Micrometer
Observation</a> uses own, more generic, terminology and provides the general
APIs to denote the <strong>Observation </strong>lifecycle (which somewhat is
analogous to <strong>Span</strong>) and injection points to propagate the
context across many distributed components. As such, the intrinsic details
about HTTP headers f.e. becomes an integral part of the distributed tracer of
your choice, out of reach for
Apache CXF.</p><div class="confluence-information-macro
confluence-information-macro-information"><span class="aui-icon aui-icon-small
aui-iconfont-info confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p><a shape="rect"
class="external-link" href="https://github.com/micrometer-metrics/tracing";
rel="nofollow">Micrometer Tracing</a> provides a simple facade for the most
popular tracer libraries, letting to implement the instrumentation of the
JVM-based application code without vendor lock-in. It is designed to add little
to no overhead to the tracing collection activity while maximizing the
portability of the tracing efforts.</p></div></div><h1
id="UsingMicrometerObservation-DistributedTracinginApacheCXFusingMicrometerObservation">Distributed
Tracing in Apache CXF using Micrometer Observation</h1><p>The current
integration of the <a shape="rect" class="external-link"
href="https://micrometer.io/docs/observation"; rel="nofollow">Micrometer Observ
ation</a>'s distributed tracing in <a shape="rect"
href="http://cxf.apache.org/";>Apache CXF</a> supports <a shape="rect"
class="external-link" href="https://micrometer.io/docs/observation";
rel="nofollow">Micrometer Observation</a> <strong>1</strong><strong
class="external-link">.10.x</strong> /  <a shape="rect"
class="external-link" href="https://micrometer.io/docs/tracing";
rel="nofollow">Micrometer Tracing</a> <strong>1.0.x</strong> and provides
full-fledged support of JAX-RS 2.x / JAX-WS applications. From high-level
prospective, the JAX-RS integration consists of three main
parts:</p><ul><li><strong>TracerContext</strong> (injectable through
<strong>@Context</strong>
annotation)</li><li><strong>ObservationProvider</strong> (server-side JAX-RS
provider) and <strong>Observation</strong><strong>ClientProvider</strong>
(client-side JAX-RS provider)</li><li
class="external-link"><strong>ObservationFeature</strong> (server-side JAX-RS
feature) to simplify the configuration and int
egration</li></ul><p>Similarly, from high-level perspective, JAX-WS
integration includes:</p><ul><li><strong>ObservationStartInterceptor</strong> /
<strong>Observation</strong><strong>StopInterceptor</strong> /
<strong>Observation</strong><strong>Feature </strong><a shape="rect"
href="http://cxf.apache.org/";>Apache CXF</a> feature (server-side JAX-WS
support)</li><li><strong>ObservationClientStartInterceptor</strong> /
<strong>Observation</strong><strong>ClientStopInterceptor</strong> /
<strong>Observation</strong><strong>ClientFeature </strong><a shape="rect"
href="http://cxf.apache.org/";>Apache CXF</a> feature (client-side JAX-WS
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 specific to
distributing tracing framework you have picked and are not configurable at the
moment (unless the framework itself has a way to do
that).</p><p>By default,
<strong>Observation</strong><strong>ClientProvider</strong> will use configured
propagators to pass the currently active <strong>observation</strong> through
HTTP headers on each service invocation. If there is no active observations,
the new observation will be created and passed through HTTP headers on
per-invocation basis. Essentially, for JAX-RS applications just registering
<strong>Observation</strong><strong>ClientProvider</strong> on the client and
<strong>Observation</strong><strong>Provider</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 reporter(s) /
exporter(s)</strong> and <strong>sampler(s)</strong> which are, not
surprisingly, specific to distributing tracing bridge you have chosen.</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>observations</stron
g> (<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 HTTP method, f.e.: <strong>GET books, POST book/123</strong></p><h1
id="UsingMicrometerObservation-ConfiguringClient">Configuring
Client</h1><p>There are a couple of ways the JAX-RS client could be configured,
depending on the tracing bridge you want to use (see please <a shape="rect"
class="external-link"
href="https://micrometer.io/docs/tracing#_configuring_with_micrometer_observation";
rel="nofollow">Configuring with Micrometer Observation</a>). The <a
shape="rect" href="http://cxf.apache.org/";>Apache CXF</a> provides its own
<strong>WebClient</strong> which could be config
ured 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">final
ObservationRegistry observationRegistry = ObservationRegistry.create();
@@ -125,8 +126,9 @@ final Propagator propagator = <create
observationRegistry.observationConfig().observationHandler(
new FirstMatchingCompositeObservationHandler(
new PropagatingSenderTracingObservationHandler<>(tracer,
propagator),
- new PropagatingReceiverTracingObservationHandler<>(tracer,
propagator)
- )
+ new PropagatingReceiverTracingObservationHandler<>(tracer,
propagator),
+ new DefaultTracingObservationHandler(tracer)
+     )
);
Response response = WebClient
@@ -146,8 +148,9 @@ public class CatalogApplication extends
observationRegistry.observationConfig().observationHandler(
  new FirstMatchingCompositeObservationHandler(
new PropagatingSenderTracingObservationHandler<>(tracer,
propagator),
- new
PropagatingReceiverTracingObservationHandler<>(tracer, propagator)
- )
+ new
PropagatingReceiverTracingObservationHandler<>(tracer, propagator),
+ new DefaultTracingObservationHandler(tracer)
+             )
);
return new HashSet<>(
@@ -166,8 +169,9 @@ final Propagator propagator = <create
observationRegistry.observationConfig().observationHandler(
new FirstMatchingCompositeObservationHandler(
new PropagatingSenderTracingObservationHandler<>(tracer,
propagator),
- new PropagatingReceiverTracingObservationHandler<>(tracer,
propagator)
- )
+ new PropagatingReceiverTracingObservationHandler<>(tracer,
propagator),
+ new DefaultTracingObservationHandler(tracer)
+     )
);
final JAXRSServerFactoryBean factory =
RuntimeDelegate.getInstance().createEndpoint(/* application instance */,
JAXRSServerFactoryBean.class);
@@ -207,7 +211,8 @@ final OtelTracer tracer = new OtelTracer
observationRegistry.observationConfig().observationHandler(
new FirstMatchingCompositeObservationHandler(
new PropagatingSenderTracingObservationHandler<>(tracer,
propagator),
- new PropagatingReceiverTracingObservationHandler<>(tracer,
propagator)
+ new PropagatingReceiverTracingObservationHandler<>(tracer,
propagator),
+ new DefaultTracingObservationHandler(tracer)      
 
)
);</pre>
</div></div><h2
id="UsingMicrometerObservation-Example#1:ClientandServerwithdefaultdistributedtracingconfigured">Example
#1: Client and Server with default distributed tracing configured</h2><p>In
the first example we are going to see the effect of using default configuration
on the client and on the server, with only <strong><span style="color:
rgb(0,0,0);">ObservationClientProvider </span></strong>and <strong><span
style="color: rgb(0,0,0);">Observation</span>Provider</strong> registered. The
JAX-RS resource endpoint is pretty basic stubbed method:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
@@ -224,7 +229,131 @@ public Collection<Book> getBooks()
.request()
.accept(MediaType.APPLICATION_JSON)
.get();</pre>
-</div></div><p>The actual invocation of the request by the client (with
service name <strong>tracer-client</strong>) and consequent invocation of the
service on the server side (service name<strong> tracer-server</strong>) is
going to generate the following sample traces (taken from <a shape="rect"
class="external-link" href="https://github.com/uber/jaeger-ui";
rel="nofollow">Jaeger UI</a>):</p><p><span
class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image" draggable="false" width="900"
src="using-micrometer-observation.data/image-2023-9-14_21-20-50.png"></span></p><h2
id="UsingMicrometerObservation-Example#2:ClientandServerwithnestedtrace">Example
#2: Client and Server with nested trace</h2><p>TBD</p><h2
id="UsingMicrometerObservation-Example#3:ClientandServertracewithannotations">Example
#3: Client and Server trace with annotations</h2><p>TBD</p><h2
id="UsingMicrometerObservation-Example#4:ClientandServerwithbinaryannotations
(key/value)">Example #4: Client and Server with binary annotations
(key/value)</h2><p>TBD</p><h2
id="UsingMicrometerObservation-Example#5:ClientandServerwithparalleltrace(involvingthreadpools)">Example
#5: Client and Server with parallel trace (involving thread
pools)</h2><p>TBD</p><h2
id="UsingMicrometerObservation-Example#6:ClientandServerwithasynchronousJAX-RSservice(server-side)">Example
#6: Client and Server with asynchronous JAX-RS service
(server-side)</h2><p>TBD</p><h2
id="UsingMicrometerObservation-Example#7:ClientandServerwithasynchronousinvocation(client-side)">Example
#7: Client and Server with asynchronous invocation
(client-side)</h2><p>TBD</p><h1
id="UsingMicrometerObservation-DistributedTracingwithMicrometerObservationandJAX-WSsupport">Distributed
Tracing with Micrometer Observation and JAX-WS support</h1><p>TBD</p><h1
id="UsingMicrometerObservation-AccessingMicrometerObservationAPIs">Accessing Micrometer
Observation APIs</h1><p>The <a shape="rect" href="ht
tp://cxf.apache.org/">Apache CXF</a>  abstracts as much of the
tracer-specific APIs behind <strong>TracerContext</strong> as possible.
However, sometimes there is a need to get access to  <a shape="rect"
class="external-link" href="https://micrometer.io/docs/observation";
rel="nofollow">Micrometer Observation</a> APIs in order to leverages the rich
set of available instrumentations. To make it possible,
<strong>TracerContext</strong> has a dedicated <strong>unwrap</strong> method
which returns underlying <strong>Tracer</strong> instance. The snippet below
shows off how to use this API and use <a shape="rect" class="external-link"
href="https://micrometer.io/docs/observation"; rel="nofollow">Micrometer
Observation</a> instrumentation for <a shape="rect" class="external-link"
href="https://github.com/OpenFeign/feign-opentracing"; rel="nofollow">OpenFeign
client</a> through <strong>MicrometerObservationCapability</strong>.</p><div
class="code panel pdl" style="border-width: 1px;
"><div class="codeContent panelContent pdl">
+</div></div><p>The actual invocation of the request by the client (with
service name <strong>tracer-client</strong>) and consequent invocation of the
service on the server side (service name<strong> tracer-server</strong>) is
going to generate the following sample traces (taken from <a shape="rect"
class="external-link" href="https://github.com/uber/jaeger-ui";
rel="nofollow">Jaeger UI</a>):</p><p><span
class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image" draggable="false" width="900"
src="using-micrometer-observation.data/image-2023-9-14_21-20-50.png"></span></p><h2
id="UsingMicrometerObservation-Example#2:ClientandServerwithnestedtrace">Example
#2: Client and Server with nested trace</h2><p>In this example server-side
implementation of the JAX-RS service is going to call an external system
(simulated as a simple delay of 500ms) within its own span. The client-side
code stays unchanged.</p><div class="code panel pdl" style="
border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">@Produces( {
MediaType.APPLICATION_JSON } )
+@GET
+public Collection<Book> getBooks(@Context final TracerContext tracer)
throws Exception {
+ try(final ObservationScope scope = tracer.startSpan("Calling External
System")) {
+ // Simulating a delay of 500ms required to call external system
+ Thread.sleep(500);
+
+ return Arrays.asList(
+ new Book("Apache CXF Web Service Development", "Naveen Balani,
Rajeev Hathi")
+ );
+ }
+}</pre>
+</div></div><p>The actual invocation of the request by the client (with
service name <strong><span class="label label-default service-filter-label
service-tag-filtered">tracer-client</span></strong>) and consequent invocation
of the service on the server side (service name<strong><span class="label
label-default service-filter-label"> tracer-server</span></strong><span
class="label label-default service-filter-label">)</span> is going to generate
the following sample traces (taken from <a shape="rect" class="external-link"
href="https://github.com/uber/jaeger-ui"; rel="nofollow">Jaeger
UI</a>):</p><p><span class="confluence-embedded-file-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image"
draggable="false" width="900"
src="using-micrometer-observation.data/image-2023-9-14_21-45-17.png"></span></p><h2
id="UsingMicrometerObservation-Example#3:ClientandServertracewithannotations">Example
#3: Client and Server trace with annotations</h2><p>In this example serv
er-side implementation of the JAX-RS service is going to add timeline to the
active span. The client-side code stays unchanged.</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">@Produces( {
MediaType.APPLICATION_JSON } )
+@GET
+public Collection<Book> getBooks(@Context final TracerContext tracer)
throws Exception {
+ tracer.timeline("Preparing Books");
+ // Simulating some work using a delay of 100ms
+ Thread.sleep(100);
+
+ return Arrays.asList(
+ new Book("Apache CXF Web Service Development", "Naveen Balani, Rajeev
Hathi")
+ );
+}</pre>
+</div></div><p>The actual invocation of the request by the client (with
service name <strong><span class="label label-default service-filter-label
service-tag-filtered">tracer-client</span></strong>) and consequent invocation
of the service on the server side (service name<strong> <span class="label
label-default service-filter-label">traceser-server</span></strong>) is going
to generate the following sample traces (taken from <a shape="rect"
class="external-link" href="https://github.com/uber/jaeger-ui";
rel="nofollow">Jaeger UI</a>):</p><p><span
class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image" draggable="false" width="900"
src="using-micrometer-observation.data/image-2023-9-14_22-15-19.png"></span></p><div
class="confluence-information-macro
confluence-information-macro-information"><span class="aui-icon aui-icon-small
aui-iconfont-info confluence-information-macro-icon"></span><div
class="confluence-information-macro-b
ody"><p>Please notice that timelines are treated as<strong> logs
events</strong> in <a shape="rect" class="external-link"
href="https://uber.github.io/jaeger/";
rel="nofollow">Jaeger</a>.</p></div></div><h2
id="UsingMicrometerObservation-Example#4:ClientandServerwithbinaryannotations(key/value)">Example
#4: Client and Server with binary annotations (key/value)</h2><p>In this
example server-side implementation of the JAX-RS service is going to add
key/value annotations to the active span. The client-side code stays
unchanged.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">@Produces( {
MediaType.APPLICATION_JSON } )
+@GET
+public Collection<Book> getBooks(@Context final TracerContext tracer)
throws Exception {
+ final Collection<Book> books = Arrays.asList(
+ new Book("Apache CXF Web Service Development", "Naveen Balani, Rajeev
Hathi")
+ );
+
+ tracer.annotate("# of books", Integer.toString(books.size()));
+ return books;
+}</pre>
+</div></div><p>The actual invocation of the request by the client (with
service name <strong><span class="label label-default service-filter-label
service-tag-filtered">tracer-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 server trace properties (taken from <a
shape="rect" class="external-link" href="https://github.com/uber/jaeger-ui";
rel="nofollow">Jaeger UI</a>):</p><p><span
class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image" draggable="false" width="900"
src="using-micrometer-observation.data/image-2023-9-14_22-17-50.png"></span></p><h2
id="UsingMicrometerObservation-Example#5:ClientandServerwithparalleltrace(involvingthreadpools)">Example
#5: Client and Server with parallel trace (involving thread pools)</h2><p>In
this example server-s
ide implementation of the JAX-RS service is going to offload some work into
thread pool and then return the response to the client, simulating parallel
execution. The client-side code stays unchanged.</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">@Produces( {
MediaType.APPLICATION_JSON } )
+@GET
+public Collection<Book> getBooks(@Context final TracerContext tracer)
throws Exception {
+ final Future<Book> book1 = executor.submit(
+ tracer.wrap("Getting Book 1", new Traceable<Book>() {
+ public Book call(final TracerContext context) throws Exception {
+ // Simulating a delay of 100ms required to call external system
+ Thread.sleep(100);
+
+ return new Book("Apache CXF Web Service Development",
+ "Naveen Balani, Rajeev Hathi");
+ }
+ })
+ );
+
+ final Future<Book> book2 = executor.submit(
+ tracer.wrap("Getting Book 2", new Traceable<Book>() {
+ public Book call(final TracerContext context) throws Exception {
+ // Simulating a delay of 100ms required to call external system
+ Thread.sleep(200);
+
+ return new Book("Developing Web Services with Apache CXF and
Axis2",
+ "Kent Ka Iok Tong");
+ }
+ })
+ );
+
+ return Arrays.asList(book1.get(), book2.get());
+}</pre>
+</div></div><p>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 (process name<strong>
tracer-<span class="label label-default
service-filter-label">server</span></strong>) is going to generate the
following sample traces (taken from <a shape="rect" class="external-link"
href="https://github.com/uber/jaeger-ui"; rel="nofollow">Jaeger
UI</a>):</p><p><span class="confluence-embedded-file-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image"
draggable="false" width="900"
src="using-micrometer-observation.data/image-2023-9-14_22-19-42.png"></span></p><h2
id="UsingMicrometerObservation-Example#6:ClientandServerwithasynchronousJAX-RSservice(server-side)">Example
#6: Client and Server with asynchronous JAX-RS service (server-side)</h2><p>In
this example server-side implemen
tation of the JAX-RS service is going to be executed asynchronously. It poses
a challenge from the tracing prospective as request and response are processed
in different threads (in general). At the moment, <a shape="rect"
href="http://cxf.apache.org/";>Apache CXF</a> does not support the transparent
tracing spans management (except for default use case) but provides the simple
ways to do that (by letting to transfer spans from thread to thread). The
client-side code stays unchanged.</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">@Produces( {
MediaType.APPLICATION_JSON } )
+@GET
+public void getBooks(@Suspended final AsyncResponse response, @Context final
TracerContext tracer) throws Exception {
+ tracer.continueSpan(new Traceable<Future<Void>>() {
+ public Future<Void> call(final TracerContext context) throws
Exception {
+ return executor.submit(
+ tracer.wrap("Getting Book", new Traceable<Void>() {
+ public Void call(final TracerContext context) throws
Exception {
+ // Simulating a processing delay of 50ms
+ Thread.sleep(50);
+
+ response.resume(
+ Arrays.asList(
+ new Book("Apache CXF Web Service Development",
"Naveen Balani, Rajeev Hathi")
+ )
+ );
+
+ return null;
+ }
+ })
+ );
+ }
+ });
+}</pre>
+</div></div><p>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 (taken from <a shape="rect" class="external-link"
href="https://github.com/uber/jaeger-ui"; rel="nofollow">Jaeger
UI</a>):</p><p><span class="confluence-embedded-file-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image"
draggable="false" width="900"
src="using-micrometer-observation.data/image-2023-9-14_22-22-5.png"></span></p><h2
id="UsingMicrometerObservation-Example#7:ClientandServerwithasynchronousinvocation(client-side)">Example
#7: Client and Server with asynchronous invocation (client-side)</h2><p>In
this example server-side implementation o
f the JAX-RS service is going to be the default one:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">@Produces( {
MediaType.APPLICATION_JSON } )
+@GET
+public Collection<Book> getBooks() {
+ return Arrays.asList(
+ new Book("Apache CXF Web Service Development", "Naveen Balani, Rajeev
Hathi")
+ );
+}</pre>
+</div></div><p>While the JAX-RS client implementation is going to perform the
asynchronous invocation:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">final
Future<Response> future = client
+ .target("http://localhost:8282/books";)
+ .request()
+ .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 (taken from <a shape="rect"
class="external-link" href="https://github.com/uber/jaeger-ui";
rel="nofollow">Jaeger UI</a>):</p><p><span
class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image"
draggable="false" width="900"
src="using-micrometer-observation.data/image-2023-9-14_22-24-11.png"></span></p><h1
id="UsingMicrometerObservation-DistributedTracingwithMicrometerObservationandJAX-WSsupport">Distributed
Tracing with Micrometer Observation 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://micrometer.io/docs/observation"; rel="nofollow">Micrometer
Observation</a> APIs directly (the JAX-WS integration is going to be enhanced
in the future). Essentially, from the server-side prospective the in/out
interceptors, <strong>ObservationStartInterceptor</strong> and
<strong>Observation</strong><strong>StopInterceptor </strong>respectively,
should be configured as part of interceptor chains, either manually or using
<strong>Observation</strong><strong>Feature</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">final
ObservationRegistry observationRegistry = ObservationRegistry.create();
+// Configure tracing bridge, propagators, etc...
+
+final JaxWsServerFactoryBean sf = new JaxWsServerFactoryBean();
+...
+sf.getFeatures().add(new ObservationFeature( observationRegistry ));
+...
+sf.create();</pre>
+</div></div><p>Similarly to the server-side, client-side needs own set of
out/in interceptors,
<strong>Observation</strong><strong>ClientStartInterceptor</strong> and
<strong>Observation</strong><strong>ClientStopInterceptor</strong> (or
<strong>Observation</strong><strong>ClientFeature</strong>). Please notice the
difference from server-side: 
<strong>ObservationClientStartInterceptor</strong> becomes out-interceptor
while <strong>Observation</strong><strong>ClientStopInterceptor</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">final
ObservationRegistry observationRegistry = ObservationRegistry.create();
+// Configure tracing bridge, propagators, etc...
+
+final JaxWsProxyFactoryBean sf = new JaxWsProxyFactoryBean();
+...
+sf.getFeatures().add(new ObservationClientFeature(observationRegistry));
+...
+sf.create();</pre>
+</div></div><h1
id="UsingMicrometerObservation-AccessingMicrometerObservationAPIs">Accessing Micrometer
Observation APIs</h1><p>The <a shape="rect"
href="http://cxf.apache.org/";>Apache CXF</a>  abstracts as much of the
tracer-specific APIs behind <strong>TracerContext</strong> as possible.
However, sometimes there is a need to get access to  <a shape="rect"
class="external-link" href="https://micrometer.io/docs/observation";
rel="nofollow">Micrometer Observation</a> APIs in order to leverages the rich
set of available instrumentations. To make it possible,
<strong>TracerContext</strong> has a dedicated <strong>unwrap</strong> method
which returns underlying <strong>Tracer</strong> instance. The snippet below
shows off how to use this API and use <a shape="rect" class="external-link"
href="https://micrometer.io/docs/observation"; rel="nofollow">Micrometer
Observation</a> instrumentation for <a shape="rect" class="external-link"
href="https://github.com/OpenFeign/feign-op
entracing" rel="nofollow">OpenFeign client</a> through
<strong>MicrometerObservationCapability</strong>.</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default">@GET
@Path("/search")
@Produces(MediaType.APPLICATION_JSON)
@@ -241,7 +370,7 @@ public JsonObject search(@QueryParam("q"
}
</pre>
-</div></div><h1 id="UsingMicrometerObservation-Usingnon-JAX-RSclients">Using
non-JAX-RS clients</h1><p>The  <a shape="rect"
href="http://cxf.apache.org/";>Apache CXF</a>  uses native <a shape="rect"
class="external-link" href="https://micrometer.io/docs/observation";
rel="nofollow">Micrometer Observation</a> capabilities so the existing
instrumentations for different HTTP clients work as expected. The usage of only
JAX-RS client is not required.</p></div>
+</div></div><h1 id="UsingMicrometerObservation-Usingnon-JAX-RSclients">Using
non-JAX-RS clients</h1><p>The  <a shape="rect"
href="http://cxf.apache.org/";>Apache CXF</a>  uses native <a shape="rect"
class="external-link" href="https://micrometer.io/docs/observation";
rel="nofollow">Micrometer Observation</a> capabilities so the existing
instrumentations for different HTTP clients work as expected. The usage of only
JAX-RS client is not required.</p><h1
id="UsingMicrometerObservation-Samples">Samples</h1><ul style="list-style-type:
square;"><li><a shape="rect" class="external-link"
href="https://github.com/apache/cxf/tree/main/distribution/src/main/release/samples/jax_rs/tracing_micrometer";
rel="nofollow">https://github.com/apache/cxf/tree/main/distribution/src/main/release/samples/jax_rs/tracing_micrometer</a></li></ul></div>
</div>
<!-- Content -->
</td>
