You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cxf.apache.org by bu...@apache.org on 2023/08/20 18:42:53 UTC
svn commit: r1083979 - in /websites/production/cxf/content: cache/docs.pageCache docs/using-opentelemetry.html
Author: buildbot
Date: Sun Aug 20 18:42:53 2023
New Revision: 1083979
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/using-opentelemetry.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/cxf/content/docs/using-opentelemetry.html
==============================================================================
--- websites/production/cxf/content/docs/using-opentelemetry.html (original)
+++ websites/production/cxf/content/docs/using-opentelemetry.html Sun Aug 20 18:42:53 2023
@@ -98,7 +98,16 @@ Apache CXF -- Using OpenTelemetry
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"><h1 id="UsingOpenTelemetry-Overview">Overview</h1><p><a shape="rect" class="external-link" href="https://opentelemetry.io/" rel="nofollow">OpenTelemetry</a> (formed through a merger of the <a shape="rect" class="external-link" href="http://opentracing.io/" rel="nofollow">OpenTracing</a> and <a shape="rect" class="external-link" href="https://opencensus.io/" rel="nofollow">OpenCensus</a> projects) is a collection of APIs, SDKs, and tools to instrument, generate, collect, and export telemetry data like metrics, logs, and distributed traces. <a shape="rect" class="external-link" href="https://opentelemetry.io/" rel="nofollow">OpenTelemetry</a> is vendor-neutral open-source <a shape="rect" class="external-link" href="https://opentelemetry.io/docs/concepts/observability-primer/#what-is-observability" rel="nofollow">observability</a> framework and as an industry-standard, it is <a shape="rect" class="external-link" href="https://opentelemetry.io/ecosystem/vendo
rs/" rel="nofollow">natively supported by a number of vendors</a>. From the instrumentation perspective, there is support for quite a few programming languages, including dedicated <a shape="rect" class="external-link" href="https://github.com/open-telemetry/opentelemetry-java" rel="nofollow">Java APIs</a>. Starting from <strong>3.5.7 /3.6.2</strong> <strong>/ 4.0.3</strong> releases, Apache CXF fully supports integration (through <strong>cxf-integration-tracing-opentelemetry </strong>module) with <a shape="rect" class="external-link" href="https://opentelemetry.io/" rel="nofollow">OpenTelemetry</a> distributed tracing capabilities.</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 basics however <a shape="rect" class="external-link" href="https://opentelemetry.io/" rel="nofollow">OpenTelemetry</a> specification abstracts a lot of thing
s, outlining just a general APIs to denote the <strong>Span </strong>lifecycle 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><h1 id="UsingOpenTelemetry-DistributedTracinginApacheCXFusingOpenTelemetry">Distributed Tracing in Apache CXF using OpenTelemetry</h1><p>The current integration of the <a shape="rect" class="external-link" href="https://opentelemetry.io/" rel="nofollow">OpenTelemetry</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://github.com/open-telemetry/opentelemetry-java" rel="nofollow">OpenTelemetry Java SDK</a> <strong>1</strong><strong class="external-link">.28.0+</strong> (using <a shape="rect" class="external-link" href="https://github.com/open-telemetry/opentelemetry-ja
va/blob/main/semconv" rel="nofollow">semantic conventions</a>) 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>OpenTelemetryProvider</strong> (server-side JAX-RS provider) and <strong>OpenTelemetryClientProvider</strong> (client-side JAX-RS provider)</li><li class="external-link"><strong>OpenTelemetryFeature</strong> (server-side JAX-RS feature) to simplify the configuration and integration</li></ul><p>Similarly, from high-level perspective, JAX-WS integration includes:</p><ul><li><strong>OpenTelemetryStartInterceptor</strong> / <strong>OpenTelemetryStopInterceptor</strong> / <strong>OpenTelemetryFeature </strong><a shape="rect" href="http://cxf.apache.org/">Apache CXF</a> feature (server-side JAX-WS support)</li><li><strong>OpenTelemetryClientStartInterceptor<
/strong> / <strong>OpenTelemetryClientStopInterceptor</strong> / <strong>OpenTelemetryClientFeature </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>OpenTelemetryClientProvider</strong> will use configured propagators 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>OpenTelemetryClientProvider</strong> on the client and <strong>Open
TelemetryProvider</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 exporters(s)</strong> and <strong>sampler(s)</strong> which are, not surprisingly, specific to distributing tracing vendor 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>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></div>
+<div id="ConfluenceContent"><h1 id="UsingOpenTelemetry-/*<![CDATA[*/div.rbtoc1692556969562{padding:0px;}div.rbtoc1692556969562ul{margin-left:0px;}div.rbtoc1692556969562li{margin-left:0px;padding-left:0px;}/*]]>*/#UsingOpenTelemetry-Overview#UsingOpenTelemetry-OverviewDistributedTracinginApa"><style type="text/css">/*<![CDATA[*/
+div.rbtoc1692556969562 {padding: 0px;}
+div.rbtoc1692556969562 ul {margin-left: 0px;}
+div.rbtoc1692556969562 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</style></h1><div class="toc-macro rbtoc1692556969562">
+<ul class="toc-indentation"><li><a shape="rect" href="#UsingOpenTelemetry-"></a></li><li><a shape="rect" href="#UsingOpenTelemetry-Overview">Overview</a></li><li><a shape="rect" href="#UsingOpenTelemetry-DistributedTracinginApacheCXFusingOpenTelemetry">Distributed Tracing in Apache CXF using OpenTelemetry</a></li><li><a shape="rect" href="#UsingOpenTelemetry-ConfiguringClient">Configuring Client</a></li><li><a shape="rect" href="#UsingOpenTelemetry-ConfiguringServer">Configuring Server</a></li><li><a shape="rect" href="#UsingOpenTelemetry-DistributedTracingInAction:UsageScenarios">Distributed Tracing In Action: Usage Scenarios</a>
+<ul class="toc-indentation"><li><a shape="rect" href="#UsingOpenTelemetry-Example#1:ClientandServerwithdefaultdistributedtracingconfigured">Example #1: Client and Server with default distributed tracing configured</a></li><li><a shape="rect" href="#UsingOpenTelemetry-Example#2:ClientandServerwithnestedtrace">Example #2: Client and Server with nested trace</a></li><li><a shape="rect" href="#UsingOpenTelemetry-Example#3:ClientandServertracewithannotations">Example #3: Client and Server trace with annotations</a></li><li><a shape="rect" href="#UsingOpenTelemetry-Example#4:ClientandServerwithbinaryannotations(key/value)">Example #4: Client and Server with binary annotations (key/value)</a></li><li><a shape="rect" href="#UsingOpenTelemetry-Example#5:ClientandServerwithparalleltrace(involvingthreadpools)">Example #5: Client and Server with parallel trace (involving thread pools)</a></li><li><a shape="rect" href="#UsingOpenTelemetry-Example#6:ClientandServerwithasynchronousJAX-RSservice(se
rver-side)">Example #6: Client and Server with asynchronous JAX-RS service (server-side)</a></li><li><a shape="rect" href="#UsingOpenTelemetry-Example#7:ClientandServerwithasynchronousinvocation(client-side)">Example #7: Client and Server with asynchronous invocation (client-side)</a></li></ul>
+</li><li><a shape="rect" href="#UsingOpenTelemetry-DistributedTracingwithOpenTelemetryandJAX-WSsupport">Distributed Tracing with OpenTelemetry and JAX-WS support</a></li><li><a shape="rect" href="#UsingOpenTelemetry-DistributedTracingwithOpenTelemetryandOSGi">Distributed Tracing with OpenTelemetry and OSGi</a></li><li><a shape="rect" href="#UsingOpenTelemetry-SpringXML-Configuration">Spring XML-Configuration</a></li><li><a shape="rect" href="#UsingOpenTelemetry-Usingnon-JAX-RSclients">Using non-JAX-RS clients</a></li></ul>
+</div><h1 id="UsingOpenTelemetry-Overview">Overview</h1><p><a shape="rect" class="external-link" href="https://opentelemetry.io/" rel="nofollow">OpenTelemetry</a> (formed through a merger of the <a shape="rect" class="external-link" href="http://opentracing.io/" rel="nofollow">OpenTracing</a> and <a shape="rect" class="external-link" href="https://opencensus.io/" rel="nofollow">OpenCensus</a> projects) is a collection of APIs, SDKs, and tools to instrument, generate, collect, and export telemetry data like metrics, logs, and distributed traces. <a shape="rect" class="external-link" href="https://opentelemetry.io/" rel="nofollow">OpenTelemetry</a> is vendor-neutral open-source <a shape="rect" class="external-link" href="https://opentelemetry.io/docs/concepts/observability-primer/#what-is-observability" rel="nofollow">observability</a> framework and as an industry-standard, it is <a shape="rect" class="external-link" href="https://opentelemetry.io/ecosystem/vendors/" rel="nofollow">na
tively supported by a number of vendors</a>. From the instrumentation perspective, there is support for quite a few programming languages, including dedicated <a shape="rect" class="external-link" href="https://github.com/open-telemetry/opentelemetry-java" rel="nofollow">Java APIs</a>. Starting from <strong>3.5.7 /3.6.2</strong> <strong>/ 4.0.3</strong> releases, Apache CXF fully supports integration (through <strong>cxf-integration-tracing-opentelemetry </strong>module) with <a shape="rect" class="external-link" href="https://opentelemetry.io/" rel="nofollow">OpenTelemetry</a> distributed tracing capabilities.</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 basics however <a shape="rect" class="external-link" href="https://opentelemetry.io/" rel="nofollow">OpenTelemetry</a> specification abstracts a lot of things, outlining just a ge
neral APIs to denote the <strong>Span </strong>lifecycle 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><h1 id="UsingOpenTelemetry-DistributedTracinginApacheCXFusingOpenTelemetry">Distributed Tracing in Apache CXF using OpenTelemetry</h1><p>The current integration of the <a shape="rect" class="external-link" href="https://opentelemetry.io/" rel="nofollow">OpenTelemetry</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://github.com/open-telemetry/opentelemetry-java" rel="nofollow">OpenTelemetry Java SDK</a> <strong>1</strong><strong class="external-link">.28.0+</strong> (using <a shape="rect" class="external-link" href="https://github.com/open-telemetry/opentelemetry-java/blob/main/semconv"
rel="nofollow">semantic conventions</a>) 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>OpenTelemetryProvider</strong> (server-side JAX-RS provider) and <strong>OpenTelemetryClientProvider</strong> (client-side JAX-RS provider)</li><li class="external-link"><strong>OpenTelemetryFeature</strong> (server-side JAX-RS feature) to simplify the configuration and integration</li></ul><p>Similarly, from high-level perspective, JAX-WS integration includes:</p><ul><li><strong>OpenTelemetryStartInterceptor</strong> / <strong>OpenTelemetryStopInterceptor</strong> / <strong>OpenTelemetryFeature </strong><a shape="rect" href="http://cxf.apache.org/">Apache CXF</a> feature (server-side JAX-WS support)</li><li><strong>OpenTelemetryClientStartInterceptor</strong> / <strong>Ope
nTelemetryClientStopInterceptor</strong> / <strong>OpenTelemetryClientFeature </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>OpenTelemetryClientProvider</strong> will use configured propagators 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>OpenTelemetryClientProvider</strong> on the client and <strong>OpenTelemetryProvider</str
ong> on the server is enough to have tracing context to be properly passed everywhere. The only configuration part which is necessary are <strong>span exporters(s)</strong> and <strong>sampler(s)</strong> which are, not surprisingly, specific to distributing tracing vendor 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>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="UsingOpenTelemetry-ConfiguringClient">Configuring Client</h1><p>TBD</p><h1 id="UsingOpenTelem
etry-ConfiguringServer">Configuring Server</h1><p>TBD</p><h1 id="UsingOpenTelemetry-DistributedTracingInAction:UsageScenarios">Distributed Tracing In Action: Usage Scenarios</h1><p>TBD</p><h2 id="UsingOpenTelemetry-Example#1:ClientandServerwithdefaultdistributedtracingconfigured">Example #1: Client and Server with default distributed tracing configured</h2><p>TBD</p><h2 id="UsingOpenTelemetry-Example#2:ClientandServerwithnestedtrace">Example #2: Client and Server with nested trace</h2><p>TBD</p><h2 id="UsingOpenTelemetry-Example#3:ClientandServertracewithannotations">Example #3: Client and Server trace with annotations</h2><p>TBD</p><h2 id="UsingOpenTelemetry-Example#4:ClientandServerwithbinaryannotations(key/value)">Example #4: Client and Server with binary annotations (key/value)</h2><p>TBD</p><h2 id="UsingOpenTelemetry-Example#5:ClientandServerwithparalleltrace(involvingthreadpools)">Example #5: Client and Server with parallel trace (involving thread pools)</h2><p>TBD</p><h2 id="
UsingOpenTelemetry-Example#6:ClientandServerwithasynchronousJAX-RSservice(server-side)">Example #6: Client and Server with asynchronous JAX-RS service (server-side)</h2><p>TBD</p><h2 id="UsingOpenTelemetry-Example#7:ClientandServerwithasynchronousinvocation(client-side)">Example #7: Client and Server with asynchronous invocation (client-side)</h2><p>TBD</p><h1 id="UsingOpenTelemetry-DistributedTracingwithOpenTelemetryandJAX-WSsupport">Distributed Tracing with OpenTelemetry and JAX-WS support</h1><p>TBD</p><h1 id="UsingOpenTelemetry-DistributedTracingwithOpenTelemetryandOSGi">Distributed Tracing with OpenTelemetry and OSGi</h1><p>TBD</p><h1 id="UsingOpenTelemetry-SpringXML-Configuration">Spring XML-Configuration</h1><p>TBD</p><h1 id="UsingOpenTelemetry-Usingnon-JAX-RSclients">Using non-JAX-RS clients</h1><p>TBD</p><p><br clear="none"></p></div>
</div>
<!-- Content -->
</td>