This is an automated email from the ASF dual-hosted git repository. pcongiusti pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/camel.git
commit c538cd038a54363cfa70df6a2772f82aca979989 Author: Pasquale Congiusti <[email protected]> AuthorDate: Thu Aug 21 15:08:29 2025 +0200 feat(doc): camel micrometer observability --- bom/camel-bom/pom.xml | 5 + .../org/apache/camel/catalog/others.properties | 1 + .../catalog/others}/micrometer-observability.json | 6 +- components/camel-micrometer-observability/pom.xml | 14 ++- .../services/org/apache/camel/other.properties | 4 +- .../resources/micrometer-observability.json | 6 +- .../src/main/docs/micrometer-observability.adoc | 130 +++++++++++++++------ .../observability/CamelOpenTelemetryExtension.java | 1 - .../camel-telemetry/src/main/docs/telemetry.adoc | 1 + components/pom.xml | 1 + proposals/tracing.adoc | 6 +- 11 files changed, 126 insertions(+), 49 deletions(-) diff --git a/bom/camel-bom/pom.xml b/bom/camel-bom/pom.xml index 17926cad0fe..ea253969858 100644 --- a/bom/camel-bom/pom.xml +++ b/bom/camel-bom/pom.xml @@ -1462,6 +1462,11 @@ <artifactId>camel-micrometer</artifactId> <version>4.15.0-SNAPSHOT</version> </dependency> + <dependency> + <groupId>org.apache.camel</groupId> + <artifactId>camel-micrometer-observability</artifactId> + <version>4.15.0-SNAPSHOT</version> + </dependency> <dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-micrometer-prometheus</artifactId> diff --git a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/others.properties b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/others.properties index db8c8a21f6e..8e61de3c759 100644 --- a/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/others.properties +++ b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/others.properties @@ -26,6 +26,7 @@ lra mail-microsoft-oauth main management +micrometer-observability micrometer-prometheus microprofile-config microprofile-fault-tolerance diff --git a/components/camel-micrometer-observability/src/generated/resources/micrometer-observability.json b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/others/micrometer-observability.json similarity index 76% copy from components/camel-micrometer-observability/src/generated/resources/micrometer-observability.json copy to catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/others/micrometer-observability.json index afce5fe6f33..855df7f96f7 100644 --- a/components/camel-micrometer-observability/src/generated/resources/micrometer-observability.json +++ b/catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/others/micrometer-observability.json @@ -2,14 +2,14 @@ "other": { "kind": "other", "name": "micrometer-observability", - "title": "Micrometer Observability", + "title": "Micrometer Observability 2", "description": "Micrometer Observability implementation of Camel Telemetry", "deprecated": false, - "firstVersion": "4.12.0", + "firstVersion": "4.15.0", "label": "monitoring,microservice", "supportLevel": "Preview", "groupId": "org.apache.camel", "artifactId": "camel-micrometer-observability", - "version": "4.12.0-SNAPSHOT" + "version": "4.15.0-SNAPSHOT" } } diff --git a/components/camel-micrometer-observability/pom.xml b/components/camel-micrometer-observability/pom.xml index a03b8e9fc05..dbc3befbdeb 100644 --- a/components/camel-micrometer-observability/pom.xml +++ b/components/camel-micrometer-observability/pom.xml @@ -23,7 +23,7 @@ <parent> <groupId>org.apache.camel</groupId> <artifactId>components</artifactId> - <version>4.12.0-SNAPSHOT</version> + <version>4.15.0-SNAPSHOT</version> </parent> <artifactId>camel-micrometer-observability</artifactId> @@ -60,13 +60,14 @@ <!-- START Required to validate a real context propagation implementation --> <dependency> - <groupId>io.micrometer</groupId> - <artifactId>micrometer-tracing-bridge-otel</artifactId> + <groupId>io.opentelemetry</groupId> + <artifactId>opentelemetry-sdk</artifactId> + <version>${opentelemetry-version}</version> <scope>test</scope> </dependency> <dependency> <groupId>io.opentelemetry</groupId> - <artifactId>opentelemetry-sdk</artifactId> + <artifactId>opentelemetry-api</artifactId> <version>${opentelemetry-version}</version> <scope>test</scope> </dependency> @@ -76,6 +77,11 @@ <version>${opentelemetry-version}</version> <scope>test</scope> </dependency> + <dependency> + <groupId>io.micrometer</groupId> + <artifactId>micrometer-tracing-bridge-otel</artifactId> + <scope>test</scope> + </dependency> <!-- END Required to validate a real context propagation implementation --> <dependency> <groupId>org.apache.camel</groupId> diff --git a/components/camel-micrometer-observability/src/generated/resources/META-INF/services/org/apache/camel/other.properties b/components/camel-micrometer-observability/src/generated/resources/META-INF/services/org/apache/camel/other.properties index c2cf3f73b4f..1961ffade91 100644 --- a/components/camel-micrometer-observability/src/generated/resources/META-INF/services/org/apache/camel/other.properties +++ b/components/camel-micrometer-observability/src/generated/resources/META-INF/services/org/apache/camel/other.properties @@ -2,6 +2,6 @@ name=micrometer-observability groupId=org.apache.camel artifactId=camel-micrometer-observability -version=4.12.0-SNAPSHOT -projectName=Camel :: Micrometer :: Observability +version=4.15.0-SNAPSHOT +projectName=Camel :: Micrometer :: Observability 2 projectDescription=Micrometer Observability implementation of Camel Telemetry diff --git a/components/camel-micrometer-observability/src/generated/resources/micrometer-observability.json b/components/camel-micrometer-observability/src/generated/resources/micrometer-observability.json index afce5fe6f33..855df7f96f7 100644 --- a/components/camel-micrometer-observability/src/generated/resources/micrometer-observability.json +++ b/components/camel-micrometer-observability/src/generated/resources/micrometer-observability.json @@ -2,14 +2,14 @@ "other": { "kind": "other", "name": "micrometer-observability", - "title": "Micrometer Observability", + "title": "Micrometer Observability 2", "description": "Micrometer Observability implementation of Camel Telemetry", "deprecated": false, - "firstVersion": "4.12.0", + "firstVersion": "4.15.0", "label": "monitoring,microservice", "supportLevel": "Preview", "groupId": "org.apache.camel", "artifactId": "camel-micrometer-observability", - "version": "4.12.0-SNAPSHOT" + "version": "4.15.0-SNAPSHOT" } } diff --git a/components/camel-micrometer-observability/src/main/docs/micrometer-observability.adoc b/components/camel-micrometer-observability/src/main/docs/micrometer-observability.adoc index e2d8e70461e..98d24ed46e8 100644 --- a/components/camel-micrometer-observability/src/main/docs/micrometer-observability.adoc +++ b/components/camel-micrometer-observability/src/main/docs/micrometer-observability.adoc @@ -1,18 +1,24 @@ -= Telemetry Dev Component -:doctitle: Micrometer Observability -:shortname: micrometed-observability -:artifactid: camel-micrometed-observability -:description: Implementation of Camel Micrometer Observability based on the Camel Telemetry spec += Micrometer Observability 2 Component +:doctitle: Micrometer Observability 2 +:shortname: micrometer-observability +:artifactid: camel-micrometer-observability +:description: Micrometer Observability implementation of Camel Telemetry :since: 4.15 :supportlevel: Preview :tabs-sync-option: *Since Camel {since}* -This module is the implementation of the common `camel-telemetry` interface based on https://micrometer.io/[Micrometer Application Observability] technology. The name used here as `Micrometer Observability 2` is done to distinguish on the existing `camel-observation` component which was based on an older Camel tracing and Micrometer specification. You're invited to start replacing the older `camel-observation` with this one instead as it may become the default component in future version [...] +This module is the implementation of the common `camel-telemetry` interface based on https://micrometer.io/[Micrometer Application Observability] technology. The name used here as `Micrometer Observability 2` is done to distinguish on the existing `camel-observation` component which was based on an older Camel tracing and Micrometer Observability specification. You're invited to start replacing the older `camel-observation` with this one instead as it may become the default component in [...] + +This component is significantly more difficult to setup than other telemetry components. This is because you will need to configure the tracing mechanism at a low level. If you're looking for a telemetry component to configure in a simpler fashion you may have a look at the others `camel-telemetry` implementations. NOTE: this component has slight differences compared to the `camel-observation` and is meant to solve a few inconsistencies identified. +== Micrometer Application Observability framework + +Mind that the framework is an abstraction layer, therefore it is expected that the integration developers configure the Registry and the Context Propagation mechanisms (more info in a dedicated chapter later) adding the concrete technology (Opentelemetry, Brave/Zipkin) of choice. + == Configuration The configuration properties for the component are: @@ -23,47 +29,101 @@ The configuration properties for the component are: |`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. -|`traceProcessors` | `false` | Setting this to true will create new OpenTelemetry Spans for each Camel Processors. +|`traceProcessors` | `false` | Setting this to true will create new spans for each Camel Processors. Use the excludePattern property to filter out Processors |======================================================================= -== Tracing format +=== Using with standalone Camel + +If you use `camel-main` as standalone Camel, add `camel-micrometer-observability` component in your POM, and setup the proper configuration. Mind that, since the component is a facade to a concrete implementation, you are in charge to provide the configuration programmatically. The minimum required for the component to start is the following snippet of code: -The component provides a few different traces representation formats you can use, depending on the scope of your telemetry or the integration with any third party telemetry collectors. +```java +import org.apache.camel.micrometer.observability.MicrometerObservabilityTracer; +... + @Override + public void configure() throws Exception { + MicrometerObservabilityTracer myTracer = new MicrometerObservabilityTracer(); + getContext().getRegistry().bind("myTracer", myTracer); + myTracer.init(getContext()); + ... + } +``` -=== Tree +You can run this, for example, directly via Camel JBang using `camel run MyTest.java --dep camel-micrometer-observability`. This basic configuration will start an "in-memory" simple implementation with a "no-op" context propagation. You may want to use this exclusively for development purposes. In order to configure it for a production environment you will need to setup a `Tracer`, an `ObservationRegistry` and a `Propagator`. -As the component is mainly targeted to have a quick visualization of a running application, then, the `tree` format is the recommended one. The output will be like the following: +If you need to setup the specific component parameters, you may do it directly on the tracer object, for example: -``` -| d6c36bc6f3374ed0bd6edb638535f130 -├── | timer://start (camel-timer) [2030 millis] <-- - ├── | process (to1-to) [2021 millis] - ├── | direct://new (camel-direct) [2020 millis] --> - ├── | direct://new (camel-direct) [2019 millis] <-- - ├── | process (delay1-delay) [2002 millis] - ├── | process (log2-log) [2 millis] - └── | process (to3-to) [3 millis] - └── | log://new (camel-log) [2 millis] --> - └── | process (to4-to) [1 millis] - └── | mock://end (camel-mock) [0 millis] --> - ├── | process (log1-log) [0 millis] - └── | process (to2-to) [2 millis] - └── | log://info (camel-log) [1 millis] --> +```java + myTracer.setTraceProcessors(true); + myTracer.setExcludePatterns("log*,to*"); ``` -This is a quick visual tree Trace representation of a given execution of a Camel route. You can quickly verify the Camel URI, the component and the time spent to execute each Span. +The production configuration vary based on the concrete technology you use (likely, `Opentelemetry` or `Brave/Zipkin`). What you need to do is to include the specific Maven dependency and to bind a concrete implementation for each of the following beans: + + * io.micrometer.tracing.Tracer + * io.micrometer.observation.ObservationRegistry + * io.micrometer.tracing.propagation.Propagator + +=== Opentelemetry example + +Here it follows an example to configure the component to work with Opentelemetry bridge. First of all, you need to include in your project the dependencies for `io.micrometer:micrometer-tracing-bridge-otel` and `io.opentelemetry:opentelemetry-sdk:x.y.z` (you need to explicitly set the version for the last dependency). + +```java +import org.apache.camel.micrometer.observability.MicrometerObservabilityTracer; +import io.micrometer.tracing.otel.bridge.OtelCurrentTraceContext; +import io.micrometer.tracing.otel.bridge.OtelPropagator; +import io.micrometer.tracing.otel.bridge.OtelTracer; +import io.opentelemetry.sdk.OpenTelemetrySdk; +import io.opentelemetry.sdk.trace.SdkTracerProvider; +import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor; +//import io.opentelemetry.exporter.zipkin.ZipkinSpanExporter; +import io.opentelemetry.context.propagation.ContextPropagators; +import io.opentelemetry.api.trace.propagation.W3CTraceContextPropagator; +... + + SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder() + // inmemory implementation + .addSpanProcessor(SimpleSpanProcessor.create( + io.opentelemetry.sdk.testing.exporter.InMemorySpanExporter.create())) + // or + // .addSpanProcessor( + // BatchSpanProcessor.builder( + // ZipkinSpanExporter.builder() + // .setEndpoint("http://localhost:9411/api/v2/spans";) + // .build() + // ).build() + // which requires a Zipkin server listening to that port + // ) + .build(); + ContextPropagators propagators = ContextPropagators.create( + W3CTraceContextPropagator.getInstance()); + OpenTelemetrySdk openTelemetry = OpenTelemetrySdk.builder() + .setTracerProvider(sdkTracerProvider) + .setPropagators(propagators) + .build(); + io.opentelemetry.api.trace.Tracer otelTracer = + openTelemetry.getTracer("camel-app"); + io.micrometer.tracing.Tracer micrometerTracer = new OtelTracer( + otelTracer, + new OtelCurrentTraceContext(), + null); + OtelPropagator otelPropagator = new OtelPropagator(propagators, otelTracer); + getContext().getRegistry().bind("MicrometerObservabilityTracer", micrometerTracer); + getContext().getRegistry().bind("OpentelemetryPropagators", otelPropagator); + MicrometerObservabilityTracer myTracer = new MicrometerObservabilityTracer(); + getContext().getRegistry().bind("myTracer", myTracer); + myTracer.init(getContext()); + ... +``` -NOTE: the --> and <-- represents an outgoing or incoming message. +NOTE: this is an example that can be used as a reference. It may not work exactly as it is, since, the related dependency can change from version to version. You will need to check in details looking at the concrete implementation documentation. -=== Json +You can see that the configuration of this component may get a bit difficult, unless you are already familiar with the tracing technology you're going to implement. -This format is suitable if you need to integrate with any third party. The output of each trace will come in the following format: +=== How to trace -```json -{"traceId":"4ee161eb055644fca713f4c02ab2fb50","spans":[{"logEntries":[],"traceid":"4ee161eb055644fca713f4c02ab2fb50","spanid":"8785debcdc09409abeed65d08aaaca1b","exchangeId":"D1B1814C509A376-0000000000000000","op":"EVENT_RECEIVED","component":"camel-timer","url.path":"start","initTimestamp":"4085653460994","camel.uri":"timer://start","url.scheme":"timer","endTimestamp":"4087698388888","isDone":"true"},{"logEntries":[],"traceid":"4ee161eb055644fca713f4c02ab2fb50","spanid":"51cc3929d34e452 [...] -``` +Once the application is instrumented and configured, you can observe the traces produced with the tooling compatible to the concrete implementation you have in place. You are invited to follow the specific documentation of each technology. -=== Default +=== Java Agents -Default is a very simple serialization into the default Java object `toString()` representation. +Your application may require a Java agent in order to get the traces generated by the Camel application and push to the tracing server (ie, Opentelemetry based instrumentation). You may need to configure such agent (or any other tool) directly via Java parameters. diff --git a/components/camel-micrometer-observability/src/test/java/org/apache/camel/micrometer/observability/CamelOpenTelemetryExtension.java b/components/camel-micrometer-observability/src/test/java/org/apache/camel/micrometer/observability/CamelOpenTelemetryExtension.java index a5e8a199b77..e54393fa393 100644 --- a/components/camel-micrometer-observability/src/test/java/org/apache/camel/micrometer/observability/CamelOpenTelemetryExtension.java +++ b/components/camel-micrometer-observability/src/test/java/org/apache/camel/micrometer/observability/CamelOpenTelemetryExtension.java @@ -73,7 +73,6 @@ final class CamelOpenTelemetryExtension implements BeforeEachCallback, AfterEach InMemoryMetricReader metricReader = InMemoryMetricReader.create(); SdkMeterProvider meterProvider = SdkMeterProvider.builder().registerMetricReader(metricReader).build(); - InMemoryLogRecordExporter logRecordExporter = InMemoryLogRecordExporter.create(); SdkLoggerProvider loggerProvider = SdkLoggerProvider.builder() .addLogRecordProcessor(SimpleLogRecordProcessor.create(logRecordExporter)) diff --git a/components/camel-telemetry/src/main/docs/telemetry.adoc b/components/camel-telemetry/src/main/docs/telemetry.adoc index 29ea79ed42c..b8cecaa42da 100644 --- a/components/camel-telemetry/src/main/docs/telemetry.adoc +++ b/components/camel-telemetry/src/main/docs/telemetry.adoc @@ -12,6 +12,7 @@ This module is a common interface and API for distributed tracing/telemetry. It is not intended to be used directly by end users. This component is implemented concretely in following dependencies: * camel-opentelemetry2 +* camel-micrometer-observability * camel-telemetry-dev Tracing an application in a distributed deployment is an important feature supported by Camel. As there are plenty of potential telemetry implementation out there we have created an abstract component whose goal is to define the structure and lifecycle of a trace from Camel point of view. This component acts as a trace manager, making sure that regardless of the concrete technology used, the traces are consistently treated by Camel applications. diff --git a/components/pom.xml b/components/pom.xml index 711ab1b6b05..80541a9cba3 100644 --- a/components/pom.xml +++ b/components/pom.xml @@ -216,6 +216,7 @@ <module>camel-mapstruct</module> <module>camel-metrics</module> <module>camel-micrometer</module> + <module>camel-micrometer-observability</module> <module>camel-micrometer-prometheus</module> <module>camel-microprofile</module> <module>camel-mina</module> diff --git a/proposals/tracing.adoc b/proposals/tracing.adoc index 7bb9c1d76a1..1c41d3e9b80 100644 --- a/proposals/tracing.adoc +++ b/proposals/tracing.adoc @@ -126,6 +126,10 @@ Developed first draft component which cover this document specification. We have Developed concrete mock/debugging component implementing the `camel-telemetry` specification that can be used for development purposes. -=== `camel-telemetry2` component (2025-02-24) +=== `camel-opentelemetry2` component (2025-02-24) Developed concrete OpenTelemetry component implementing the `camel-telemetry` specification. This component will eventually replace `camel-opentelemetry` component. + +=== `camel-micrometer-observability` component (2025-08-21) + +Developed concrete Micrometer Observability component implementing the `camel-telemetry` specification. This component will eventually replace `camel-observation` component. \ No newline at end of file
