OpenTelemetry

Since Camel 3.5

The OpenTelemetry component is used for tracing and timing incoming and outgoing Camel messages using OpenTelemetry.

Events (spans) are captured for incoming and outgoing messages being sent to/from Camel.

Configuration

The configuration properties for the OpenTelemetry tracer are:

Option Default Description

instrumentationName

camel

A name uniquely identifying the instrumentation scope, such as the instrumentation library, package, or fully qualified class name. Must not be null.

excludePatterns

Sets exclude pattern(s) that will disable tracing for Camel messages that matches the pattern. The content is a Set<String> where the key is a pattern. The pattern uses the rules from Intercept.

encoding

false

Sets whether the header keys need to be encoded (connector specific) or not. The value is a boolean. Dashes are required for instances to be encoded for JMS property keys.

traceProcessors

false

Setting this to true will create new OpenTelemetry Spans for each Camel Processors. Use the excludePattern property to filter out Processors

Using Camel OpenTelemetry

Include the camel-opentelemetry component in your POM, along with any specific dependencies associated with the chosen OpenTelemetry compliant Tracer.

To explicitly configure OpenTelemetry support, instantiate the OpenTelemetryTracer and initialize the camel context. You can optionally specify a Tracer, or alternatively it can be implicitly discovered using the Registry

OpenTelemetryTracer otelTracer = new OpenTelemetryTracer();
// By default, it uses the DefaultTracer, but you can override it with a specific OpenTelemetry Tracer implementation.
otelTracer.setTracer(...);
// And then initialize the context
otelTracer.init(camelContext);
You would still need OpenTelemetry to instrument your code, which can be done via a Java agent.

Using with standalone Camel

If you use camel-main as standalone Camel, then you can enable and use OpenTelemetry without Java code.

Add camel-opentelemetry component in your POM, and configure in application.properties:

camel.opentelemetry.enabled = true
# you can configure the other options
# camel.opentelemetry.instrumentationName = myApp
You would still need OpenTelemetry to instrument your code, which can be done via a Java agent.

Spring Boot

If you are using Spring Boot, just add the camel-opentelemetry-starter dependency to get started.

OpenTelemetry’s Tracer will be configured through spring-boot-starter-actuator unless a Tracer is already defined.

Noteworthy: by default, Spring Boot samples only 10% of requests to prevent overwhelming the trace backend. Set the property management.tracing.sampling.probability to 1.0 if you want to see all traces.

SpanExporters

You’ll probably want to configure at least one SpanExporter as they allow you to export your traces to various backends (e.g Zipkin and Jaeger) or log them. For example, to export your traces to Jaeger using OTLP via gRPC, add io.opentelemetry:opentelemetry-exporter-otlp as a dependency to your project. To configure it, you can use the management.otlp.tracing properties or register a new SpanExporter bean yourself:

@Bean
public SpanExporter OtlpGrpcSpanExporter(@Value("${tracing.url}") String url) {
    return OtlpGrpcSpanExporter.builder().setEndpoint(url).build();
}

Spring Boot’s Actuator will take care of the wiring for you.

Alternatively if you just want to log your traces in OTLP JSON format, add io.opentelemetry:opentelemetry-exporter-logging-otlp as a dependency to your project and also register a new SpanExporter bean:

@Bean
public SpanExporter logTraces() {
    return OtlpJsonLoggingSpanExporter.create();
}

Multiple SpanExporters can be used at the same time.

Java Agent

Download the latest version.

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.

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

By default, the OpenTelemetry Java agent uses OTLP exporter configured to send data to OpenTelemetry collector at http://localhost:4318.

Configuration parameters are passed as Java system properties (-D flags) or as environment variables. See the configuration documentation for the full list of configuration items. For example:

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

Spring Boot Auto-Configuration

When using opentelemetry with Spring Boot make sure to use the following Maven dependency to have support for auto configuration:

<dependency>
  <groupId>org.apache.camel.springboot</groupId>
  <artifactId>camel-opentelemetry-starter</artifactId>
  <version>x.x.x</version>
  <!-- use the same version as your Camel core version -->
</dependency>

The component supports 4 options, which are listed below.

Name Description Default Type

camel.opentelemetry.enabled

Global option to enable/disable OpenTelemetry integration, default is true.

true

Boolean

camel.opentelemetry.encoding

Activate or deactivate dash encoding in headers (required by JMS) for messaging.

Boolean

camel.opentelemetry.exclude-patterns

Sets exclude pattern(s) that will disable tracing for Camel messages that matches the pattern. Multiple patterns can be separated by comma.

String

camel.opentelemetry.trace-processors

Setting this to true will create new OpenTelemetry Spans for each Camel Processors. Use the excludePattern property to filter out Processors.

Boolean

MDC Logging

When MDC Logging is enabled for the active Camel context the Trace ID and Span ID will be added and removed from the MDC for each route, the keys are trace_id and span_id, respectively.

Back to top