Skip to content

Commit c538cd0

Browse files
squakezsquakez
committed
feat(doc): camel micrometer observability
1 parent 553ddd5 commit c538cd0

File tree

11 files changed

+138
-46
lines changed

11 files changed

+138
-46
lines changed

‎bom/camel-bom/pom.xml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1462,6 +1462,11 @@
14621462
<artifactId>camel-micrometer</artifactId>
14631463
<version>4.15.0-SNAPSHOT</version>
14641464
</dependency>
1465+
<dependency>
1466+
<groupId>org.apache.camel</groupId>
1467+
<artifactId>camel-micrometer-observability</artifactId>
1468+
<version>4.15.0-SNAPSHOT</version>
1469+
</dependency>
14651470
<dependency>
14661471
<groupId>org.apache.camel</groupId>
14671472
<artifactId>camel-micrometer-prometheus</artifactId>

‎catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/others.properties

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ lra
2626
mail-microsoft-oauth
2727
main
2828
management
29+
micrometer-observability
2930
micrometer-prometheus
3031
microprofile-config
3132
microprofile-fault-tolerance

‎catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/others/micrometer-observability.json

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"other": {
3+
"kind": "other",
4+
"name": "micrometer-observability",
5+
"title": "Micrometer Observability 2",
6+
"description": "Micrometer Observability implementation of Camel Telemetry",
7+
"deprecated": false,
8+
"firstVersion": "4.15.0",
9+
"label": "monitoring,microservice",
10+
"supportLevel": "Preview",
11+
"groupId": "org.apache.camel",
12+
"artifactId": "camel-micrometer-observability",
13+
"version": "4.15.0-SNAPSHOT"
14+
}
15+
}

‎components/camel-micrometer-observability/pom.xml

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323
<parent>
2424
<groupId>org.apache.camel</groupId>
2525
<artifactId>components</artifactId>
26-
<version>4.12.0-SNAPSHOT</version>
26+
<version>4.15.0-SNAPSHOT</version>
2727
</parent>
2828

2929
<artifactId>camel-micrometer-observability</artifactId>
@@ -60,13 +60,14 @@
6060

6161
<!-- START Required to validate a real context propagation implementation -->
6262
<dependency>
63-
<groupId>io.micrometer</groupId>
64-
<artifactId>micrometer-tracing-bridge-otel</artifactId>
63+
<groupId>io.opentelemetry</groupId>
64+
<artifactId>opentelemetry-sdk</artifactId>
65+
<version>${opentelemetry-version}</version>
6566
<scope>test</scope>
6667
</dependency>
6768
<dependency>
6869
<groupId>io.opentelemetry</groupId>
69-
<artifactId>opentelemetry-sdk</artifactId>
70+
<artifactId>opentelemetry-api</artifactId>
7071
<version>${opentelemetry-version}</version>
7172
<scope>test</scope>
7273
</dependency>
@@ -76,6 +77,11 @@
7677
<version>${opentelemetry-version}</version>
7778
<scope>test</scope>
7879
</dependency>
80+
<dependency>
81+
<groupId>io.micrometer</groupId>
82+
<artifactId>micrometer-tracing-bridge-otel</artifactId>
83+
<scope>test</scope>
84+
</dependency>
7985
<!-- END Required to validate a real context propagation implementation -->
8086
<dependency>
8187
<groupId>org.apache.camel</groupId>

‎components/camel-micrometer-observability/src/generated/resources/META-INF/services/org/apache/camel/other.properties

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@
22
name=micrometer-observability
33
groupId=org.apache.camel
44
artifactId=camel-micrometer-observability
5-
version=4.12.0-SNAPSHOT
6-
projectName=Camel :: Micrometer :: Observability
5+
version=4.15.0-SNAPSHOT
6+
projectName=Camel :: Micrometer :: Observability 2
77
projectDescription=Micrometer Observability implementation of Camel Telemetry

‎components/camel-micrometer-observability/src/generated/resources/micrometer-observability.json

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,14 @@
22
"other": {
33
"kind": "other",
44
"name": "micrometer-observability",
5-
"title": "Micrometer Observability",
5+
"title": "Micrometer Observability 2",
66
"description": "Micrometer Observability implementation of Camel Telemetry",
77
"deprecated": false,
8-
"firstVersion": "4.12.0",
8+
"firstVersion": "4.15.0",
99
"label": "monitoring,microservice",
1010
"supportLevel": "Preview",
1111
"groupId": "org.apache.camel",
1212
"artifactId": "camel-micrometer-observability",
13-
"version": "4.12.0-SNAPSHOT"
13+
"version": "4.15.0-SNAPSHOT"
1414
}
1515
}

‎components/camel-micrometer-observability/src/main/docs/micrometer-observability.adoc

Lines changed: 95 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,24 @@
1-
= Telemetry Dev Component
2-
:doctitle: Micrometer Observability
3-
:shortname: micrometed-observability
4-
:artifactid: camel-micrometed-observability
5-
:description: Implementation of Camel Micrometer Observability based on the Camel Telemetry spec
1+
= Micrometer Observability 2 Component
2+
:doctitle: Micrometer Observability 2
3+
:shortname: micrometer-observability
4+
:artifactid: camel-micrometer-observability
5+
:description: Micrometer Observability implementation of Camel Telemetry
66
:since: 4.15
77
:supportlevel: Preview
88
:tabs-sync-option:
99

1010
*Since Camel {since}*
1111

12-
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 of Camel.
12+
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 future version of Camel.
13+
14+
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.
1315

1416
NOTE: this component has slight differences compared to the `camel-observation` and is meant to solve a few inconsistencies identified.
1517

18+
== Micrometer Application Observability framework
19+
20+
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.
21+
1622
== Configuration
1723

1824
The configuration properties for the component are:
@@ -23,47 +29,101 @@ The configuration properties for the component are:
2329
|`excludePatterns` | | Sets exclude pattern(s) that will disable tracing for Camel
2430
messages that matches the pattern. The content is a Set<String> where the key is a pattern. The pattern
2531
uses the rules from Intercept.
26-
|`traceProcessors` | `false` | Setting this to true will create new OpenTelemetry Spans for each Camel Processors.
32+
|`traceProcessors` | `false` | Setting this to true will create new spans for each Camel Processors.
2733
Use the excludePattern property to filter out Processors
2834
|=======================================================================
2935

30-
== Tracing format
36+
=== Using with standalone Camel
37+
38+
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:
3139

32-
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.
40+
```java
41+
import org.apache.camel.micrometer.observability.MicrometerObservabilityTracer;
42+
...
43+
@Override
44+
public void configure() throws Exception {
45+
MicrometerObservabilityTracer myTracer = new MicrometerObservabilityTracer();
46+
getContext().getRegistry().bind("myTracer", myTracer);
47+
myTracer.init(getContext());
48+
...
49+
}
50+
```
3351

34-
=== Tree
52+
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`.
3553

36-
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:
54+
If you need to setup the specific component parameters, you may do it directly on the tracer object, for example:
3755

38-
```
39-
| d6c36bc6f3374ed0bd6edb638535f130
40-
├── | timer://start (camel-timer) [2030 millis] <--
41-
├── | process (to1-to) [2021 millis]
42-
├── | direct://new (camel-direct) [2020 millis] -->
43-
├── | direct://new (camel-direct) [2019 millis] <--
44-
├── | process (delay1-delay) [2002 millis]
45-
├── | process (log2-log) [2 millis]
46-
└── | process (to3-to) [3 millis]
47-
└── | log://new (camel-log) [2 millis] -->
48-
└── | process (to4-to) [1 millis]
49-
└── | mock://end (camel-mock) [0 millis] -->
50-
├── | process (log1-log) [0 millis]
51-
└── | process (to2-to) [2 millis]
52-
└── | log://info (camel-log) [1 millis] -->
56+
```java
57+
myTracer.setTraceProcessors(true);
58+
myTracer.setExcludePatterns("log*,to*");
5359
```
5460

55-
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.
61+
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:
62+
63+
* io.micrometer.tracing.Tracer
64+
* io.micrometer.observation.ObservationRegistry
65+
* io.micrometer.tracing.propagation.Propagator
66+
67+
=== Opentelemetry example
68+
69+
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).
70+
71+
```java
72+
import org.apache.camel.micrometer.observability.MicrometerObservabilityTracer;
73+
import io.micrometer.tracing.otel.bridge.OtelCurrentTraceContext;
74+
import io.micrometer.tracing.otel.bridge.OtelPropagator;
75+
import io.micrometer.tracing.otel.bridge.OtelTracer;
76+
import io.opentelemetry.sdk.OpenTelemetrySdk;
77+
import io.opentelemetry.sdk.trace.SdkTracerProvider;
78+
import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor;
79+
//import io.opentelemetry.exporter.zipkin.ZipkinSpanExporter;
80+
import io.opentelemetry.context.propagation.ContextPropagators;
81+
import io.opentelemetry.api.trace.propagation.W3CTraceContextPropagator;
82+
...
83+
84+
SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
85+
// inmemory implementation
86+
.addSpanProcessor(SimpleSpanProcessor.create(
87+
io.opentelemetry.sdk.testing.exporter.InMemorySpanExporter.create()))
88+
// or
89+
// .addSpanProcessor(
90+
// BatchSpanProcessor.builder(
91+
// ZipkinSpanExporter.builder()
92+
// .setEndpoint("http://localhost:9411/api/v2/spans")
93+
// .build()
94+
// ).build()
95+
// which requires a Zipkin server listening to that port
96+
// )
97+
.build();
98+
ContextPropagators propagators = ContextPropagators.create(
99+
W3CTraceContextPropagator.getInstance());
100+
OpenTelemetrySdk openTelemetry = OpenTelemetrySdk.builder()
101+
.setTracerProvider(sdkTracerProvider)
102+
.setPropagators(propagators)
103+
.build();
104+
io.opentelemetry.api.trace.Tracer otelTracer =
105+
openTelemetry.getTracer("camel-app");
106+
io.micrometer.tracing.Tracer micrometerTracer = new OtelTracer(
107+
otelTracer,
108+
new OtelCurrentTraceContext(),
109+
null);
110+
OtelPropagator otelPropagator = new OtelPropagator(propagators, otelTracer);
111+
getContext().getRegistry().bind("MicrometerObservabilityTracer", micrometerTracer);
112+
getContext().getRegistry().bind("OpentelemetryPropagators", otelPropagator);
113+
MicrometerObservabilityTracer myTracer = new MicrometerObservabilityTracer();
114+
getContext().getRegistry().bind("myTracer", myTracer);
115+
myTracer.init(getContext());
116+
...
117+
```
56118

57-
NOTE: the --> and <-- represents an outgoing or incoming message.
119+
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.
58120

59-
=== Json
121+
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.
60122

61-
This format is suitable if you need to integrate with any third party. The output of each trace will come in the following format:
123+
=== How to trace
62124

63-
```json
64-
{"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":"51cc3929d34e45218d8b7eacabbd1791","exchangeId":"D1B1814C509A376-0000000000000000","op":"EVENT_PROCESS","component":"to1-to","initTimestamp":"4085657493896","endTimestamp":"4087694416371","isDone":"true","parentSpan":"8785debcdc09409abeed65d08aaaca1b"},{"logEntries":[],"traceid":"4ee161eb055644fca713f4c02ab2fb50","spanid":"d0139a2ce41840e793870aa41cee1fdb","exchangeId":"D1B1814C509A376-0000000000000000","op":"EVENT_SENT","component":"camel-direct","url.path":"new","initTimestamp":"4085658724372","camel.uri":"direct://new","url.scheme":"direct","endTimestamp":"4087694351732","isDone":"true","parentSpan":"51cc3929d34e45218d8b7eacabbd1791"},{"logEntries":[],"traceid":"4ee161eb055644fca713f4c02ab2fb50","spanid":"481705e45eb5440da3c4d80b1cb72782","exchangeId":"D1B1814C509A376-0000000000000000","op":"EVENT_RECEIVED","component":"camel-direct","url.path":"new","initTimestamp":"4085659711482","camel.uri":"direct://new","url.scheme":"direct","endTimestamp":"4087694171231","isDone":"true","parentSpan":"d0139a2ce41840e793870aa41cee1fdb"},{"logEntries":[],"traceid":"4ee161eb055644fca713f4c02ab2fb50","spanid":"f60cda25f0b94d339d4cd46c71675273","exchangeId":"D1B1814C509A376-0000000000000000","op":"EVENT_PROCESS","component":"delay1-delay","initTimestamp":"4085660053232","endTimestamp":"4087662537085","isDone":"true","parentSpan":"481705e45eb5440da3c4d80b1cb72782"},{"logEntries":[{"fields":{"message":"A new message"}}],"traceid":"4ee161eb055644fca713f4c02ab2fb50","spanid":"43f759e7904e4255937f395b2b8447ce","exchangeId":"D1B1814C509A376-0000000000000000","op":"EVENT_PROCESS","component":"log2-log","initTimestamp":"4087668469960","endTimestamp":"4087683763263","isDone":"true","parentSpan":"481705e45eb5440da3c4d80b1cb72782"},{"logEntries":[],"traceid":"4ee161eb055644fca713f4c02ab2fb50","spanid":"f84fabb0dc9e4549bf544f3e22833747","exchangeId":"D1B1814C509A376-0000000000000000","op":"EVENT_PROCESS","component":"to3-to","initTimestamp":"4087686094066","endTimestamp":"4087691026432","isDone":"true","parentSpan":"481705e45eb5440da3c4d80b1cb72782"},{"logEntries":[{"fields":{"message":"Exchange[ExchangePattern: InOnly, BodyType: null, Body: [Body is null]]"}}],"traceid":"4ee161eb055644fca713f4c02ab2fb50","spanid":"1f468061fb914db8a809ac6660b64e5f","exchangeId":"D1B1814C509A376-0000000000000000","op":"EVENT_SENT","component":"camel-log","url.path":"new","initTimestamp":"4087687679924","camel.uri":"log://new","url.scheme":"log","endTimestamp":"4087690877575","isDone":"true","parentSpan":"f84fabb0dc9e4549bf544f3e22833747"},{"logEntries":[],"traceid":"4ee161eb055644fca713f4c02ab2fb50","spanid":"124d4c89f7124941bcc3a383d0548382","exchangeId":"D1B1814C509A376-0000000000000000","op":"EVENT_PROCESS","component":"to4-to","initTimestamp":"4087692103508","endTimestamp":"4087693840549","isDone":"true","parentSpan":"481705e45eb5440da3c4d80b1cb72782"},{"logEntries":[],"traceid":"4ee161eb055644fca713f4c02ab2fb50","spanid":"d9a50630958a47fca126dd33015b8595","exchangeId":"D1B1814C509A376-0000000000000000","op":"EVENT_SENT","component":"camel-mock","url.path":"end","initTimestamp":"4087692840068","camel.uri":"mock://end","url.scheme":"mock","endTimestamp":"4087693765128","isDone":"true","parentSpan":"124d4c89f7124941bcc3a383d0548382"},{"logEntries":[{"fields":{"message":"A direct message"}}],"traceid":"4ee161eb055644fca713f4c02ab2fb50","spanid":"c63fa5fc1fef4c219ba38d4a94144bb8","exchangeId":"D1B1814C509A376-0000000000000000","op":"EVENT_PROCESS","component":"log1-log","initTimestamp":"4087695240589","endTimestamp":"4087696229225","isDone":"true","parentSpan":"8785debcdc09409abeed65d08aaaca1b"},{"logEntries":[],"traceid":"4ee161eb055644fca713f4c02ab2fb50","spanid":"a09ad1afe037420bb518e9dd1e21b096","exchangeId":"D1B1814C509A376-0000000000000000","op":"EVENT_PROCESS","component":"to2-to","initTimestamp":"4087696762964","endTimestamp":"4087698248033","isDone":"true","parentSpan":"8785debcdc09409abeed65d08aaaca1b"},{"logEntries":[{"fields":{"message":"Exchange[ExchangePattern: InOnly, BodyType: null, Body: [Body is null]]"}}],"traceid":"4ee161eb055644fca713f4c02ab2fb50","spanid":"56f736f7a8be481e8bffea23e43b7f15","exchangeId":"D1B1814C509A376-0000000000000000","op":"EVENT_SENT","component":"camel-log","url.path":"info","initTimestamp":"4087697222908","camel.uri":"log://info","url.scheme":"log","endTimestamp":"4087698189820","isDone":"true","parentSpan":"a09ad1afe037420bb518e9dd1e21b096"}]}
65-
```
125+
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.
66126

67-
=== Default
127+
=== Java Agents
68128

69-
Default is a very simple serialization into the default Java object `toString()` representation.
129+
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.

‎components/camel-micrometer-observability/src/test/java/org/apache/camel/micrometer/observability/CamelOpenTelemetryExtension.java

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,6 @@ static CamelOpenTelemetryExtension create() {
7373

7474
InMemoryMetricReader metricReader = InMemoryMetricReader.create();
7575
SdkMeterProvider meterProvider = SdkMeterProvider.builder().registerMetricReader(metricReader).build();
76-
7776
InMemoryLogRecordExporter logRecordExporter = InMemoryLogRecordExporter.create();
7877
SdkLoggerProvider loggerProvider = SdkLoggerProvider.builder()
7978
.addLogRecordProcessor(SimpleLogRecordProcessor.create(logRecordExporter))

‎components/camel-telemetry/src/main/docs/telemetry.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
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:
1313

1414
* camel-opentelemetry2
15+
* camel-micrometer-observability
1516
* camel-telemetry-dev
1617
1718
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.

‎components/pom.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -216,6 +216,7 @@
216216
<module>camel-mapstruct</module>
217217
<module>camel-metrics</module>
218218
<module>camel-micrometer</module>
219+
<module>camel-micrometer-observability</module>
219220
<module>camel-micrometer-prometheus</module>
220221
<module>camel-microprofile</module>
221222
<module>camel-mina</module>

0 commit comments

Comments
 (0)