This is an automated email from the ASF dual-hosted git repository.
jamesnetherton pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new f7a5a9a0d290 camel-opentelemetry2: Minor documentation improvements
f7a5a9a0d290 is described below
commit f7a5a9a0d290d36044cf056ae5d85a7af7545425
Author: James Netherton <[email protected]>
AuthorDate: Thu Feb 5 08:46:42 2026 +0000
camel-opentelemetry2: Minor documentation improvements
---
.../src/main/docs/opentelemetry2.adoc | 75 ++++++++++++++--------
1 file changed, 48 insertions(+), 27 deletions(-)
diff --git a/components/camel-opentelemetry2/src/main/docs/opentelemetry2.adoc
b/components/camel-opentelemetry2/src/main/docs/opentelemetry2.adoc
index 960f56b1ba4a..5005970bf9d0 100644
--- a/components/camel-opentelemetry2/src/main/docs/opentelemetry2.adoc
+++ b/components/camel-opentelemetry2/src/main/docs/opentelemetry2.adoc
@@ -11,9 +11,11 @@
*Since Camel {since}*
-This module is the implementation of the common `camel-telemetry` interface
based on https://opentelemetry.io/[OpenTelemetry] technology. The name used
here as `camel-opentelemetry2` is done to distinguish on the existing
`camel-opentelemetry` which was based on an older Camel tracing specification.
You're invited to start replacing the older `camel-opentelemetry` with this one
instead as it may become the default component in future version of Camel.
+This module is an implementation of the common `camel-telemetry` interface
based on link:++https://opentelemetry.io/[OpenTelemetry]++[OpenTelemetry]
technology.
-NOTE: this component has slight differences compared to the
`camel-openetelemetry` and is meant to solve a few inconsistencies identified.
+It is named `camel-opentelemetry2` to differentiate it from the existing
`camel-opentelemetry` component, which is based on an older Camel tracing
specification. We recommend using this new component for future projects and
migrating existing applications from `camel-opentelemetry`, as this component
will likely become the default in a future version of Camel.
+
+NOTE: This component addresses inconsistencies found in the original
`camel-opentelemetry` component and offers a more robust implementation.
== Configuration
@@ -21,42 +23,43 @@ The configuration properties for the OpenTelemetry2 tracer
are:
[width="100%",cols="10%,10%,80%",options="header",]
|=======================================================================
-|Option |Default |Description
-|`excludePatterns` | | Sets exclude pattern that will disable tracing for
those spans that matches the pattern. The variable is a comma separated values
of filters to execute (eg, `log*,direct*,setBody*`, ...)
-|`traceProcessors` | `false` | Setting this to true will create new
OpenTelemetry Spans for each Camel Processors.
-Use the excludePattern property to filter out Processors
-|`traceHeadersInclusion`| false | Add the generated telemetry `CAMEL_TRACE_ID`
and `CAMEL_SPAN_ID` Exchange headers.
+| Option | Default | Description
+| `excludePatterns` | | A comma-separated list of patterns (e.g.,
`log*,direct*,setBody*`) to exclude from tracing. Spans matching these patterns
will be disabled.
+| `traceProcessors` | `false` | If set to `true`, Camel creates OpenTelemetry
Spans for each processor in your routes. You can use `excludePatterns` to
filter which processors are traced.
+| `traceHeadersInclusion`| `false` | If set to `true`, adds the generated
telemetry `CAMEL_TRACE_ID` and `CAMEL_SPAN_ID` Exchange headers.
|=======================================================================
-=== Using with standalone Camel
+=== Using with Standalone Camel
-If you use `camel-main` as standalone Camel, then you can enable and use
OpenTelemetry without Java code.
+When using `camel-main`, you can enable and configure OpenTelemetry
declaratively in your `application.properties` file without writing any Java
code.
-Add `camel-opentelemetry2` component in your POM, and configure in
`application.properties`:
+First, add the `camel-opentelemetry2` dependency to your project `pom.xml`.
Then, add configuration options to `application.properties`:
[source,properties]
----
camel.opentelemetry2.enabled = true
-# you can configure the other options
+# Other options can also be configured
# camel.opentelemetry2.traceProcessors = true
----
-When starting the application, you may need to configure a few OpenTelemetry
SDK variables, as you can see in te following example:
+When starting your application, you may also need to configure OpenTelemetry
SDK system properties. For example:
-```bash
-$ java -Dotel.metrics.exporter=none -Dotel.logs.exporter=none -jar my-app.jar
-```
+[source,bash]
+----
+java -Dotel.metrics.exporter=none -Dotel.logs.exporter=none -jar my-app.jar
+----
[[OpenTelemetry-JavaAgent]]
-=== Java Agent
+=== Using the OpenTelemetry Java Agent
-Your application will require a Java agent in order to get the traces
generated by the Camel application and push to the tracing server.
+To capture and export traces, your application typically needs the
OpenTelemetry Java agent. The agent automatically instruments your application
to collect telemetry data.
-NOTE: certain runtimes (ie, Quarkus) may provide an inner client which pushes
traces to the server. Make sure to read each specific Camel runtime
documentation.
+NOTE: Some runtimes, such as Quarkus, provide built-in OpenTelemetry
integration and may not require a separate agent. Consult the documentation for
your specific runtime for guidance.
-Download the
https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/[latest
version].
+To use the agent:
-This package includes the instrumentation agent as well as instrumentation for
all supported libraries and all available data exporters. The package provides
a completely automatic, out-of-the-box experience. Enable the instrumentation
agent using the `-javaagent` flag to the JVM.
+. Download the latest `opentelemetry-javaagent.jar` from the
https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/[official
releases page].
+. Attach the agent to your application's JVM using the `-javaagent` flag.
[source,bash]
----
@@ -65,9 +68,11 @@ java -javaagent:path/to/opentelemetry-javaagent.jar \
-jar myapp.jar
----
-By default, the OpenTelemetry Java agent uses
https://github.com/open-telemetry/opentelemetry-java/tree/main/exporters/otlp[OTLP
exporter] configured to send data to
https://github.com/open-telemetry/opentelemetry-collector/blob/main/receiver/otlpreceiver/README.md[OpenTelemetry
collector] at `http://localhost:4318`.
+By default, the agent uses the OTLP exporter and sends data to an
https://github.com/open-telemetry/opentelemetry-collector/blob/main/receiver/otlpreceiver/README.md[OpenTelemetry
Collector] at `http://localhost:4318`.
+
+You can configure the agent using Java system properties (`-D` flags) or
environment variables. For a complete list of options, see the official
https://opentelemetry.io/docs/zero-code/java/agent/configuration/[agent
configuration documentation].
-Configuration parameters are passed as Java system properties (`-D` flags) or
as environment variables. See
https://opentelemetry.io/docs/zero-code/java/agent/configuration/[the
configuration documentation] for the full list of configuration items. For
example:
+For example, to set the service name and exporter type:
[source,bash]
----
@@ -78,13 +83,29 @@ java -javaagent:path/to/opentelemetry-javaagent.jar \
----
[[OpenTelemetry-Collection]]
-=== Collect OpenTelemetry traces
+=== Collect OpenTelemetry Traces
+
+A popular open-source choice is https://www.jaegertracing.io/[Jaeger], an
end-to-end distributed tracing system. For setup instructions, see the
https://www.jaegertracing.io/docs/latest/getting-started/[Jaeger Getting
Started guide].
-OpenTelemetry is a tracing protocol which is implemented by several vendors.
You can use the Jaeger project which provides an open source all in one tracing
application. See details how to run it in
https://www.jaegertracing.io/docs/latest/getting-started/[Jaeger getting
started guide].
+=== MDC Logging
-=== MDC logging
+To correlate logs with traces, you can include trace and span IDs in your
application's Mapped Diagnostic Context (MDC). This allows you to filter logs
for a specific trace, which is invaluable for debugging.
-You can leverage the `traceHeadersInclusion` to include the generated
`CAMEL_TRACE_ID` and `CAMEL_SPAN_ID` into the Camel Exchange and together with
`camel-mdc` you can make those headers available in the MDC context (via
`camel.mdc.customHeaders=CAMEL_TRACE_ID,CAMEL_SPAN_ID` configuration). This is
the idiomatic way in Camel.
+There are two primary ways to achieve this:
+
+.Camel MDC Integration (Recommended)
+This is the idiomatic approach for Camel applications.
+
+. Set the `traceHeadersInclusion` option to `true`. This adds `CAMEL_TRACE_ID`
and `CAMEL_SPAN_ID` to the Camel Exchange headers.
+. Use the `camel-mdc` component to automatically copy these headers into the
MDC. Configure it in `application.properties`:
++
+[source,properties]
+----
+camel.mdc.customHeaders=CAMEL_TRACE_ID,CAMEL_SPAN_ID
+----
-As an alternative, you can add Mapped Diagnostic Context tracing information
(ie, `trace_id` and `span_id`) adding the specific
https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/logger-mdc-instrumentation.md[Opentelemetry
Logger MDC auto instrumentation]. The logging configuration depends on the
logging framework you're using.
+.OpenTelemetry Agent MDC Instrumentation
+As an alternative, you can use the agent's built-in MDC integration.
+. Enable the
https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/logger-mdc-instrumentation.md[Logger
MDC auto-instrumentation]. This automatically adds `trace_id` and `span_id` to
the MDC.
+. Configure your logging framework to include these MDC keys in your log
format. The exact configuration depends on the logging library you use.
\ No newline at end of file
