Opentelemetry2

Since Camel 4.11

This module is an implementation of the common camel-telemetry interface based on OpenTelemetry technology.

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.

This component addresses inconsistencies found in the original camel-opentelemetry component and offers a more robust implementation.

Configuration

The configuration properties for the OpenTelemetry2 tracer are:

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

When using camel-main, you can enable and configure OpenTelemetry declaratively in your application.properties file without writing any Java code.

First, add the camel-opentelemetry2 dependency to your project pom.xml. Then, add configuration options to application.properties:

camel.opentelemetry2.enabled = true
# Other options can also be configured
# camel.opentelemetry2.traceProcessors = true

When starting your application, you may also need to configure OpenTelemetry SDK system properties. For example:

java -Dotel.metrics.exporter=none -Dotel.logs.exporter=none -jar my-app.jar

Using the OpenTelemetry Java Agent

To capture and export traces, your application typically needs the OpenTelemetry Java agent. The agent automatically instruments your application to collect telemetry data.

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.

To use the agent:

  1. Download the latest opentelemetry-javaagent.jar from the official releases page.

  2. Attach the agent to your application’s JVM using the -javaagent flag.

java -javaagent:path/to/opentelemetry-javaagent.jar \
     -Dotel. ... \
     -jar myapp.jar

By default, the agent uses the OTLP exporter and sends data to an 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 agent configuration documentation.

For example, to set the service name and exporter type:

java -javaagent:path/to/opentelemetry-javaagent.jar \
     -Dotel.service.name=your-service-name \
     -Dotel.traces.exporter=otlp \
     -jar myapp.jar

Collect OpenTelemetry Traces

A popular open-source choice is Jaeger, an end-to-end distributed tracing system. For setup instructions, see the Jaeger Getting Started guide.

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.

There are two primary ways to achieve this:

Camel MDC Integration (Recommended)

This is the idiomatic approach for Camel applications.

  1. Set the traceHeadersInclusion option to true. This adds CAMEL_TRACE_ID and CAMEL_SPAN_ID to the Camel Exchange headers.

  2. Use the camel-mdc component to automatically copy these headers into the MDC. Configure it in application.properties:

    camel.mdc.customHeaders=CAMEL_TRACE_ID,CAMEL_SPAN_ID
OpenTelemetry Agent MDC Instrumentation

As an alternative, you can use the agent’s built-in MDC integration.

  1. Enable the Logger MDC auto-instrumentation. This automatically adds trace_id and span_id to the MDC.

  2. Configure your logging framework to include these MDC keys in your log format. The exact configuration depends on the logging library you use.

Using the OpenTelemetry Spring Boot starter

An alternative to the OpenTelemetry agent is to use OpenTelemetry Spring Boot starter.

To ensure version alignment across all OpenTelemetry dependencies, you should import the opentelemetry-instrumentation-bom BOM.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry.instrumentation</groupId>
            <artifactId>opentelemetry-instrumentation-bom</artifactId>
            <version>2.26.1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Note: Import the OpenTelemetry BOMs before any other BOMs in your project. For example, if you import the spring-boot-dependencies BOM, you have to declare it after the OpenTelemetry BOMs. Also make sure that the version you choose is compatible with the Opentelemetry version used by the Camel version you’re using.

Then add the following dependency for the OpenTelemetry Spring Boot starter:

<dependency>
    <groupId>io.opentelemetry.instrumentation</groupId>
    <artifactId>opentelemetry-spring-boot-starter</artifactId>
</dependency>

The starter auto-configures most aspects of the OpenTelemetry instrumentation, with two exceptions: No Tracer or ContextPropagators beans are autoconfigured, they need to be configured manually:

import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.propagation.ContextPropagators;

@Configuration
public class OpenTelemetryConfiguration {

  @Bean
  public Tracer tracer(@Value("${spring.application.name}") String serviceName, OpenTelemetry openTelemetry) {
    return openTelemetry.getTracer(serviceName);
  }

  @Bean
  public ContextPropagators contextPropagators(OpenTelemetry openTelemetry) {
    return openTelemetry.getPropagators();
  }

}

The instrumentation can be configured using the standard Spring Boot configuration mechanisms (e.g. using application.yml). For a complete list of options, see the official agent configuration documentation.

For example, to set the service name and exporter type:

otel:
  service:
    name: your-service-name
  traces:
    exporter: otlp

Span customization

When you’re working at a very low level, you may need to tweak your metrics and add some in-process custom span in order to trace some specific measure of your application. If you need this advanced use case, you can create it during your process by configuring an Opentelemetry Tracer object and share it to your route. For example, in Java DSL:

private Tracer otelTracer = otelExtension.getOpenTelemetry().getTracer("traceTest");
...
public void process(Exchange exchange) throws Exception {
     exchange.getIn().setHeader("operation", "fake");
     // We add a span during the processing. We need to verify this span is correctly
     // created and belong to the proper hierarchy. Important: the user has to know which is the
     // tracer, likely, setting it on the camel-telemetry Tracer component explicitly.
     Span mySpan = otelTracer.spanBuilder("mySpan").startSpan();
     // Do the work here
     mySpan.end();
}

Baggage customization

Baggage is a way to attach key-value metadata to a request and carry it across service boundaries. In the context of OpenTelemetry, baggage travels along with the context (like trace/span), but it’s meant for custom data you define, not telemetry internals. Camel allows you to programmatically provide any Baggage information via header settings. Whenever the component finds an header defined as OTEL_BAGGAGE_xyz it will consider it as a baggage variable named xyz. For example, in Java DSL:

                from("direct:start")
                        .setHeader("OTEL_BAGGAGE_myValue", constant("1234"))
                        .routeId("start")
                        .log("A message")
                        .process(new Processor() {
                            @Override
                            public void process(Exchange exchange) throws Exception {
                                exchange.getIn().setHeader("operation", "fake");
                            }
                        })
                        .to("log:info");

Any span executed after the setHeader will include a baggage variable named myValue with value 1234 which will be reflected in your telemetry result.

any baggage setting defined externally (i.e., calling the Camel process with a context propagation) is normally going to be propagated in Camel logic.
Back to top