Author: buildbot
Date: Thu Sep 14 21:42:52 2023
New Revision: 1084172
Log:
Production update by buildbot for cxf
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.
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 Thu
Sep 14 21:42:52 2023
@@ -107,8 +107,8 @@ Apache CXF -- Using Micrometer Observati
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"><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 cho
ice, 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="nofol
low">Micrometer Observation</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.10.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 th
e configuration and integration</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 <str
ong>observations</strong> (<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 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>). <a shape="rect"
href="http://cxf.apache.org/";>Apache CXF</a> provides its own
<strong>WebClient</strong> which coul
d 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">final final
ObservationRegistry observationRegistry = ObservationRegistry.create();
+<div id="ConfluenceContent"><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 cho
ice, 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="nofol
low">Micrometer Observation</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.10.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 th
e configuration and integration</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 <str
ong>observations</strong> (<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 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">final
ObservationRegistry observationRegistry = ObservationRegistry.create();
final Tracer tracer = <create tracer using tracing bridge>;
final Propagator propagator = <create propagator using tracing bridge;
@@ -124,7 +124,48 @@ Response response = WebClient
.create("http://localhost:9000/catalog";, Arrays.asList(new
ObservationClientProvider(observationRegistry))
.accept(MediaType.APPLICATION_JSON)
.get();</pre>
-</div></div><p><br clear="none"></p><h1
id="UsingMicrometerObservation-ConfiguringServer">Configuring
Server</h1><p>TBD</p><h1
id="UsingMicrometerObservation-DistributedTracingInAction:UsageScenarios">Distributed
Tracing In Action: Usage Scenarios</h1><p>TBD</p><h2
id="UsingMicrometerObservation-Example#1:ClientandServerwithdefaultdistributedtracingconfigured">Example
#1: Client and Server with default distributed tracing
configured</h2><p>TBD</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(involv
ingthreadpools)">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>TBD</p><h1
id="UsingMicrometerObservation-Usingnon-JAX-RSclients">Using non-JAX-RS
clients</h1><p>TBD</p></div>
+</div></div><p><br clear="none"></p><h1
id="UsingMicrometerObservation-ConfiguringServer">Configuring
Server</h1><p>Server configuration is a very similar to the client one and uses
<strong>ObservationFeature</strong>, but still requires the tracing bridge
configuration (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>). Depending on the
way the <a shape="rect" href="http://cxf.apache.org/";>Apache CXF</a> is used to
configure JAX-RS services, it could be part of JAX-RS application
configuration, for example:</p><p><br clear="none"></p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">@ApplicationPath("/")
+public class CatalogApplication extends Application {
+ @Override
+ public Set<Object> getSingletons() {
+ final ObservationRegistry observationRegistry =
ObservationRegistry.create();
+
+ final Tracer tracer = <create tracer using tracing bridge>;
+ final Propagator propagator = <create propagator using tracing
bridge;
+  
+ observationRegistry.observationConfig().observationHandler(
+   new FirstMatchingCompositeObservationHandler(
+ new PropagatingSenderTracingObservationHandler<>(tracer,
propagator),
+ new
PropagatingReceiverTracingObservationHandler<>(tracer, propagator)
+ )
+ );
+
+ return new HashSet<>(
+ Arrays.asList(
+ new ObservationFeature(observationRegistry)
+ )
+ );
+ }
+}</pre>
+</div></div><p>Or it could be configured using
<strong>JAXRSServerFactoryBean</strong> as well, for example:</p><p><br
clear="none"></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();
+
+final Tracer tracer = <create tracer using tracing bridge>;
+final Propagator propagator = <create propagator using tracing bridge;
+  
+observationRegistry.observationConfig().observationHandler(
+ new FirstMatchingCompositeObservationHandler(
+ new PropagatingSenderTracingObservationHandler<>(tracer,
propagator),
+ new PropagatingReceiverTracingObservationHandler<>(tracer,
propagator)
+ )
+);
+
+final JAXRSServerFactoryBean factory =
RuntimeDelegate.getInstance().createEndpoint(/* application instance */,
JAXRSServerFactoryBean.class);
+factory.setProvider(new ObservationFeature(observationRegistry));
+...
+return factory.create();</pre>
+</div></div><p>Once the <strong>span processor(s) / reporter(s) </strong>and
<strong>sampler</strong> are properly configured, all generated
<strong>observations </strong>(<strong>spans</strong>) are going to be
collected and available for analysis and/or visualization.</p><h1
id="UsingMicrometerObservation-DistributedTracingInAction:UsageScenarios">Distributed
Tracing In Action: Usage Scenarios</h1><p>TBD</p><h2
id="UsingMicrometerObservation-Example#1:ClientandServerwithdefaultdistributedtracingconfigured">Example
#1: Client and Server with default distributed tracing
configured</h2><p>TBD</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: C
lient 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>TBD</p><h1 id="UsingMicrometerObservation-Usingnon-JAX
-RSclients">Using non-JAX-RS clients</h1><p>TBD</p></div>
</div>
<!-- Content -->
</td>
