[camel-quarkus] branch 2.13.x updated: Add OpenTelemetry documentation for CDI bean instrumentation

[ja...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

jamesnetherton pushed a commit to branch 2.13.x
in repository https://gitbox.apache.org/repos/asf/camel-quarkus.git


The following commit(s) were added to refs/heads/2.13.x by this push:
     new f01b02b765 Add OpenTelemetry documentation for CDI bean instrumentation
f01b02b765 is described below

commit f01b02b7658f4e4a4c3b48d49818430823ef4c3d
Author: James Netherton <ja...@gmail.com>
AuthorDate: Wed Apr 19 15:34:03 2023 +0100

    Add OpenTelemetry documentation for CDI bean instrumentation
---
 .../pages/reference/extensions/opentelemetry.adoc  | 38 ++++++++++++++++++++-
 .../opentelemetry/runtime/src/main/doc/usage.adoc  | 39 ++++++++++++++++++++--
 2 files changed, 74 insertions(+), 3 deletions(-)

diff --git a/docs/modules/ROOT/pages/reference/extensions/opentelemetry.adoc b/docs/modules/ROOT/pages/reference/extensions/opentelemetry.adoc
index 5eb7e0d2fe..1d4b9d0e0d 100644
--- a/docs/modules/ROOT/pages/reference/extensions/opentelemetry.adoc
+++ b/docs/modules/ROOT/pages/reference/extensions/opentelemetry.adoc
@@ -89,7 +89,7 @@ For OTLP:
 
 endif::[]
 
-Refer to the https://github.com/quarkusio/quarkus/blob/{quarkus-version}/docs/src/main/asciidoc/opentelemetry.adoc[Quarkus OpenTelemetry guide] for a full list of configuration options.
+Refer to the https://quarkus.io/guides/opentelemetry[Quarkus OpenTelemetry guide] for a full list of configuration options.
 
 Route endpoints can be excluded from tracing by configuring a property named `quarkus.camel.opentelemetry.exclude-patterns` in `application.properties`. For example:
 
@@ -99,6 +99,42 @@ Route endpoints can be excluded from tracing by configuring a property named `qu
 quarkus.camel.opentelemetry.exclude-patterns=direct:*,netty-http:*
 ----
 
+[id="extensions-opentelemetry-usage-tracing-cdi-bean-method-execution"]
+=== Tracing CDI bean method execution
+
+When instrumenting the execution of CDI bean methods from Camel routes, you should annotate such methods with `io.opentelemetry.extension.annotations.WithSpan`. Methods annotated with `@WithSpan` will create a new Span and establish any required relationships with the current Trace context.
+
+For example, to instrument a CDI bean from a Camel route, first ensure the appropriate methods are annotated with `@WithTrace`.
+
+[source,java]
+----
+@ApplicationScoped
+@Named("myBean")
+public class MyBean {
+    @WithSpan
+    public String greet() {
+        return "Hello World!";
+    }
+}
+----
+
+Next, use the bean in your Camel route.
+
+IMPORTANT: To ensure that the sequence of recorded spans is correct, you must use the full `to("bean:")` endpoint URI and not the shortened `.bean()` EIP DSL method.
+
+[source,java]
+----
+public class MyRoutes extends RouteBuilder {
+    @Override
+    public void configure() throws Exception {
+        from("direct:executeBean")
+                .to("bean:myBean?method=greet");
+    }
+}
+----
+
+There is more information about CDI instrumentation in the https://quarkus.io/guides/opentelemetry#cdi[Quarkus OpenTelemetry guide].
+
 
 [id="extensions-opentelemetry-additional-camel-quarkus-configuration"]
 == Additional Camel Quarkus configuration
diff --git a/extensions/opentelemetry/runtime/src/main/doc/usage.adoc b/extensions/opentelemetry/runtime/src/main/doc/usage.adoc
index 01842728b8..cb5717c27c 100644
--- a/extensions/opentelemetry/runtime/src/main/doc/usage.adoc
+++ b/extensions/opentelemetry/runtime/src/main/doc/usage.adoc
@@ -41,7 +41,7 @@ For OTLP:
 
 endif::[]
 
-Refer to the https://github.com/quarkusio/quarkus/blob/{quarkus-version}/docs/src/main/asciidoc/opentelemetry.adoc[Quarkus OpenTelemetry guide] for a full list of configuration options.
+Refer to the https://quarkus.io/guides/opentelemetry[Quarkus OpenTelemetry guide] for a full list of configuration options.
 
 Route endpoints can be excluded from tracing by configuring a property named `quarkus.camel.opentelemetry.exclude-patterns` in `application.properties`. For example:
 
@@ -49,4 +49,39 @@ Route endpoints can be excluded from tracing by configuring a property named `qu
 ----
 # Exclude all direct & netty-http endpoints from tracing
 quarkus.camel.opentelemetry.exclude-patterns=direct:*,netty-http:*
-----
\ No newline at end of file
+----
+
+=== Tracing CDI bean method execution
+
+When instrumenting the execution of CDI bean methods from Camel routes, you should annotate such methods with `io.opentelemetry.extension.annotations.WithSpan`. Methods annotated with `@WithSpan` will create a new Span and establish any required relationships with the current Trace context.
+
+For example, to instrument a CDI bean from a Camel route, first ensure the appropriate methods are annotated with `@WithTrace`.
+
+[source,java]
+----
+@ApplicationScoped
+@Named("myBean")
+public class MyBean {
+    @WithSpan
+    public String greet() {
+        return "Hello World!";
+    }
+}
+----
+
+Next, use the bean in your Camel route.
+
+IMPORTANT: To ensure that the sequence of recorded spans is correct, you must use the full `to("bean:")` endpoint URI and not the shortened `.bean()` EIP DSL method.
+
+[source,java]
+----
+public class MyRoutes extends RouteBuilder {
+    @Override
+    public void configure() throws Exception {
+        from("direct:executeBean")
+                .to("bean:myBean?method=greet");
+    }
+}
+----
+
+There is more information about CDI instrumentation in the https://quarkus.io/guides/opentelemetry#cdi[Quarkus OpenTelemetry guide].