OpenTelemetry Metrics

Since Camel 4.17

Only producer is supported

The OpenTelemetry Metrics component allows the collection of various metrics directly from Camel routes. Supported metric types are counter, summary, and timer.

To get started, Maven users need to add the following dependency to their pom.xml for this component:

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

URI format

opentelemetry-metrics:[ counter | summary | timer ]:metricname[?options]

Configuring Options

Camel components are configured on two separate levels:

component level
endpoint level

Configuring Component Options

At the component level, you set general and shared configurations that are, then, inherited by the endpoints. It is the highest configuration level.

For example, a component may have security settings, credentials for authentication, urls for network connection and so forth.

Some components only have a few options, and others may have many. Because components typically have pre-configured defaults that are commonly used, then you may often only need to configure a few options on a component; or none at all.

You can configure components using:

the Component DSL.
in a configuration file (application.properties, *.yaml files, etc).
directly in the Java code.

Configuring Endpoint Options

You usually spend more time setting up endpoints because they have many options. These options help you customize what you want the endpoint to do. The options are also categorized into whether the endpoint is used as a consumer (from), as a producer (to), or both.

Configuring endpoints is most often done directly in the endpoint URI as path and query parameters. You can also use the Endpoint DSL and DataFormat DSL as a type safe way of configuring endpoints and data formats in Java.

A good practice when configuring options is to use Property Placeholders.

Property placeholders provide a few benefits:

They help prevent using hardcoded urls, port numbers, sensitive information, and other settings.
They allow externalizing the configuration from the code.
They help the code to become more flexible and reusable.

The following two sections list all the options, firstly for the component followed by the endpoint.

Component Options

The OpenTelemetry Metrics component supports 3 options, which are listed below.

Name	Description	Default	Type
lazyStartProducer (producer)	Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing.	false	boolean
autowiredEnabled (advanced)	Whether autowiring is enabled. This is used for automatic autowiring options (the option must be marked as autowired) by looking up in the registry to find if there is a single instance of matching type, which then gets configured on the component. This can be used for automatic configuring JDBC data sources, JMS connection factories, AWS Clients, etc.	true	boolean
meter (advanced)	To use a custom configured Meter.		Meter

Name

Description

Default

Type

lazyStartProducer (producer)

Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing.

false

boolean

autowiredEnabled (advanced)

Whether autowiring is enabled. This is used for automatic autowiring options (the option must be marked as autowired) by looking up in the registry to find if there is a single instance of matching type, which then gets configured on the component. This can be used for automatic configuring JDBC data sources, JMS connection factories, AWS Clients, etc.

true

boolean

meter (advanced)

To use a custom configured Meter.

Meter

Endpoint Options

The OpenTelemetry Metrics endpoint is configured using URI syntax:

opentelemetry-metrics:metricType:metricName

With the following path and query parameters:

Path Parameters (2 parameters)

Name	Description	Default	Type
metricType (producer)	Required Type of metrics. Enum values: counter summary timer		InstrumentType
metricName (producer)	Required Name of metric.		String

Name

Description

Default

Type

metricType (producer)

Required Type of metrics.

Enum values:

counter
summary
timer

InstrumentType

metricName (producer)

Required Name of metric.

String

Query Parameters (8 parameters)

Name	Description	Default	Type
action (producer)	Action expression when using timer type. Enum values: start stop		String
attributes (producer)	metric attributes. This is a multi-value option with prefix: attributes.		Map
decrement (producer)	Decrement value expression when using counter type.		String
increment (producer)	Increment value expression when using counter type.		String
metricsDescription (producer)	Description of metrics.		String
unit (producer)	The time unit when using the timer type. Enum values: NANOSECONDS MICROSECONDS MILLISECONDS SECONDS MINUTES HOURS DAYS	MILLISECONDS	TimeUnit
value (producer)	Value expression when using histogram type.		String
lazyStartProducer (producer (advanced))	Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing.	false	boolean

Name

Description

Default

Type

action (producer)

Action expression when using timer type.

Enum values:

start
stop

String

attributes (producer)

metric attributes. This is a multi-value option with prefix: attributes.

Map

decrement (producer)

Decrement value expression when using counter type.

String

increment (producer)

Increment value expression when using counter type.

String

metricsDescription (producer)

Description of metrics.

String

unit (producer)

The time unit when using the timer type.

Enum values:

NANOSECONDS
MICROSECONDS
MILLISECONDS
SECONDS
MINUTES
HOURS
DAYS

MILLISECONDS

TimeUnit

value (producer)

Value expression when using histogram type.

String

lazyStartProducer (producer (advanced))

false

boolean

Message Headers

The OpenTelemetry Metrics component supports 7 message header(s), which is/are listed below:

Name Description Default Type

Name	Description	Type
CamelMetricsTimerAction (producer) Constant: `HEADER_TIMER_ACTION`	Override timer action in URI.	OpenTelemetryTimerAction
CamelMetricsHistogramValue (producer) Constant: `HEADER_HISTOGRAM_VALUE`	Override histogram value in URI.	long
CamelMetricsCounterDecrement (producer) Constant: `HEADER_COUNTER_DECREMENT`	Override decrement value in URI.	Double
CamelMetricsCounterIncrement (producer) Constant: `HEADER_COUNTER_INCREMENT`	Override increment value in URI.	Double
CamelMetricsName (producer) Constant: `HEADER_METRIC_NAME`	Override name value in URI.	String
CamelMetricsDescription (producer) Constant: `HEADER_METRIC_DESCRIPTION`	Override description value in URI.	String
CamelMetricsAttributes (producer) Constant: `HEADER_METRIC_ATTRIBUTES`	To augment meter attributes defined as URI parameters.	Attributes

CamelMetricsTimerAction (producer)

Constant: HEADER_TIMER_ACTION

Override timer action in URI.

OpenTelemetryTimerAction

CamelMetricsHistogramValue (producer)

Constant: HEADER_HISTOGRAM_VALUE

Override histogram value in URI.

long

CamelMetricsCounterDecrement (producer)

Constant: HEADER_COUNTER_DECREMENT

Override decrement value in URI.

Double

CamelMetricsCounterIncrement (producer)

Constant: HEADER_COUNTER_INCREMENT

Override increment value in URI.

Double

CamelMetricsName (producer)

Constant: HEADER_METRIC_NAME

Override name value in URI.

String

CamelMetricsDescription (producer)

Constant: HEADER_METRIC_DESCRIPTION

Override description value in URI.

String

CamelMetricsAttributes (producer)

Constant: HEADER_METRIC_ATTRIBUTES

To augment meter attributes defined as URI parameters.

Attributes

Usage

Opetntelemetry Meter

OpenTelemetry meter configuration involves setting up a MeterProvider that is responsible for creating Meter instances. These Meters are then used to create instruments like counters, gauges or histograms.

How it works

OpenTelemetry metrics are collected by instrumented application that record measurements using instruments like counters and gauges. These measurements are then processed by an OpenTelemetry SDK, which aggregates and batches them before exporting them, either directly or through the OpenTelemetry Collector. See SdkMeterProvider documentation for details on how to configure this.

Usage of producers

Each meter has a type and name. Supported types are counter, distribution summary, and timer. If no type is provided, then a counter, is used by default.

The meter name is a string that is evaluated as a Simple expression and can also be overridden using the CamelMetricsName header allowing the selection of the meter that depends on the exchange data.

The optional attributes URI parameter is a comma-separated string consisting of key=value expressions. Both key and value are strings that are evaluated as Simple expressions.

For example, the URI parameter attributes.X=${header.Y} would assign the current value of header Y to the key X.

Headers

The meter name defined in the URI can be overridden by populating a header with name CamelMetricsName. The meter attributes defined as URI parameters can be augmented by populating a header with name CamelMetricsAttributes.

For example

from("direct:in")
    .setHeader(OpenTelemetryConstants.HEADER_METRIC_NAME, constant("new.name"))
    .setHeader(OpenTelemetryConstants.HEADER_METRIC_ATTRIBUTES, constant(Attributes.of(AttributeKey.stringKey("dynamic-key"), "dynamic-value")))
    .to("opentelemetry-metrics:counter:name.not.used?attributes.key=value")
    .to("direct:out");

will update a counter with name new.name (instead of name.not.used) using the attribute dynamic-key with value dynamic-value in addition to the attribute key with value value.

All Metrics specific headers are removed from the message once the OpenTelemetry endpoint finishes processing the exchange. While processing the exchange the OpenTelemetry endpoint will catch all exceptions and write log entry using level warn.

Counter

opentelemetry-metrics:counter:name[?options]

Options

Name	Default	Description
increment	-	Long value to add to the counter
decrement	-	Long value to subtract from the counter

Name

Default

Description

increment

Long value to add to the counter

decrement

Long value to subtract from the counter

If neither increment or decrement is defined then value of the counter will be incremented by one. If increment and decrement are both defined only the increment operation is called.

// update counter 'simple.counter' by 7
from("direct:in")
    .to("opentelemetry-metrics:counter:simple.counter?increment=7")
    .to("direct:out");

// increment counter 'simple.counter' by 1
from("direct:in")
    .to("opentelemetry-metrics:counter:simple.counter")
    .to("direct:out");

Both increment and decrement values are evaluated as Simple expressions with a Long result. For instance, if header X contains a value that evaluates to 3, the counter with name simple.counter is decremented by 3:

// decrement counter 'simple.counter' by 3
from("direct:in")
    .to("opentelemetry-metrics:counter:simple.counter?decrement=${header.X}")
    .to("direct:out");

Headers

Message headers can be used to override increment and decrement values specified in the OpenTelemetry endpoint URI.

Name	Description	Expected type
CamelMetricsCounterIncrement	Override increment value in URI	Long
CamelMetricsCounterDecrement	Override decrement value in URI	Long

Name

Description

Expected type

CamelMetricsCounterIncrement

Override increment value in URI

Long

CamelMetricsCounterDecrement

Override decrement value in URI

Long

// update counter 'simple.counter' by 417
from("direct:in")
    .setHeader(OpenTelemetryConstants.HEADER_COUNTER_INCREMENT, constant(417))
    .to("opentelemetry-metrics:counter:simple.counter?increment=7")
    .to("direct:out");

// updates counter using simple language to evaluate 'body.length'
from("direct:in")
    .setHeader(OpenTelemetryConstants.HEADER_COUNTER_INCREMENT, simple("${body.length}"))
    .to("opentelemetry-metrics:counter:body.len")
    .to("direct:out");

Distribution Summary

opentelemetry-metrics:summary:metricname[?options]

Options

Name	Default	Description
value	-	Value to use in histogram

Name

Default

Description

value

Value to use in histogram

If value is not set then nothing is added to histogram and warning is logged.

// adds value 9923 to 'simple.histogram'
from("direct:in")
    .to("opentelemetry-metrics:summary:simple.histogram?value=9923")
    .to("direct:out");

// nothing is added to 'simple.histogram', and a warning is logged
from("direct:in")
    .to("opentelemetry-metrics:summary:simple.histogram")
    .to("direct:out");

The histogram value is evaluated as a Simple expressions with a Long result. For example, if header X contains a value that evaluates to 3, and this value is registered with the simple.histogram:

from("direct:in")
    .to("opentelemetry-metrics:summary:simple.histogram?value=${header.X}")
    .to("direct:out");

Headers

A specific Message header can be used to override the value specified in the OpenTelemetry endpoint URI.

Name	Description	Expected type
CamelMetricsHistogramValue	Override histogram value in URI	Long

Name

Description

Expected type

CamelMetricsHistogramValue

Override histogram value in URI

Long

// adds value 992.0 to 'simple.histogram'
from("direct:in")
    .setHeader(OpenTelemetryConstants.HEADER_HISTOGRAM_VALUE, constant(992))
    .to("opentelemetry-metrics:summary:simple.histogram?value=700")
    .to("direct:out")

Timer

opentelemetry-metrics:timer:metricname[?options]

Options

Name	Default	Description
action	-	start or stop

Name

Default

Description

action

start or stop

If no action or an invalid value is provided then a warning is logged without any timer update.

// measure time spent in route "direct:calculate"
from("direct:in")
    .to("opentelemetry-metrics:timer:simple.timer?action=start")
    .to("direct:calculate")
    .to("opentelemetry-metrics:timer:simple.timer?action=stop");

The timer action is evaluated as a Simple expression returning a result of type OpenTelemetryTimerAction. TimerTask objects are stored as Exchange properties between different Metrics component calls.

Headers

A specific Message header can be used to override action value specified in the OpenTelemetry endpoint URI.

Name Description Expected type

Name	Description	Expected type
CamelMetricsTimerAction	Override timer action in URI	`org.apache.camel.component.opentelemetry.OpenTelemetryTimerAction`

CamelMetricsTimerAction

Override timer action in URI

org.apache.camel.component.opentelemetry.OpenTelemetryTimerAction

// sets timer action using header
from("direct:in")
    .setHeader(OpenTelemetryConstants.HEADER_TIMER_ACTION, OpenTelemetryTimerAction.start)
    .to("opentelemetry-metrics:timer:simple.timer")
    .to("direct:out");

OpenTelemetry Event Notification

Camel Route Event Notifier

The Route Event Notifier counts the number of added and running routes, and can be added to the CamelContext as follows:

camelContext.getManagementStrategy().addEventNotifier(new OpenTelemetryRouteEventNotifier());

Camel specific metrics that are available:

Default Name	Type	Description
camel.routes.added	LongUpDownCounter	Number of routes in total
camel.routes.reloaded	LongCounter	Number of routes that have been reloaded
camel.routes.running	LongUpDownCounter	Number of routes currently running

Default Name

Type

Description

camel.routes.added

LongUpDownCounter

Number of routes in total

camel.routes.reloaded

LongCounter

Number of routes that have been reloaded

camel.routes.running

LongUpDownCounter

Number of routes currently running

The following options are supported:

Name	Default	Description
namingStrategy	OpenTelemetryRouteEventNotifierNamingStrategy.DEFAULT	The strategy to use for overriding default metric names.

Name

Default

Description

namingStrategy

OpenTelemetryRouteEventNotifierNamingStrategy.DEFAULT

The strategy to use for overriding default metric names.

OpenTelemetry Configuration

Applications can export collected metrics to various backends using different exporters, including the OpenTelemetry Protocol (OTLP) exporter, which is widely supported by observability platforms.

Java Agent

Your application will require a Java agent in order to get the metrics generated by the Camel application.

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 \
     -Dotel. ... \
     -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.metrics.exporter=otlp \
     -jar myapp.jar