This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new 2fb3ec2 CAMEL-16861: Cleanup and update EIP docs
2fb3ec2 is described below
commit 2fb3ec2a91027bfe19194e43be2d2aef384deca1
Author: Claus Ibsen <claus.ib...@gmail.com>
AuthorDate: Thu Sep 16 09:19:20 2021 +0200
CAMEL-16861: Cleanup and update EIP docs
---
.../modules/eips/pages/correlation-identifier.adoc | 53 +++++++++------
.../modules/eips/pages/customLoadBalancer-eip.adoc | 17 ++---
.../modules/ROOT/pages/backlog-tracer.adoc | 76 ++++++++++++----------
docs/user-manual/modules/ROOT/pages/tracer.adoc | 2 +
4 files changed, 80 insertions(+), 68 deletions(-)
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/correlation-identifier.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/correlation-identifier.adoc
index f214f77..66725f0 100644
---
a/core/camel-core-engine/src/main/docs/modules/eips/pages/correlation-identifier.adoc
+++
b/core/camel-core-engine/src/main/docs/modules/eips/pages/correlation-identifier.adoc
@@ -4,51 +4,62 @@
Camel supports the
http://www.enterpriseintegrationpatterns.com/CorrelationIdentifier.html[Correlation
Identifier] from the xref:enterprise-integration-patterns.adoc[EIP
-patterns] by getting or setting a header on a
-xref:message.adoc[Message].
+patterns] by getting or setting a header on the xref:message.adoc[Message].
When working with the xref:components::activemq-component.adoc[ActiveMQ] or
xref:components::jms-component.adoc[JMS]
components the correlation identifier header is called
-*JMSCorrelationID*. You can add your own correlation identifier to any
-message exchange to help correlate messages together to a single
-conversation (or business process).
+*JMSCorrelationID*, and they handle the correlation automatically.
+
+Other messaging systems, such as
xref:components::rabbitmq-component.adoc[RabbitMQ] also handles this automatic,
+and you should generally not have a need for using custom correlation IDs with
these systems.
image::eip/CorrelationIdentifierSolution.gif[image]
-The use of a Correlation Identifier is key to working with
xref:components:others:tracing.adoc[Tracing]
-and be useful when testing with simulation or canned data such as
-with the xref:components::mock-component.adoc[Mock testing framework]
+You can use your own correlation identifier to any
+message exchange to help correlate messages together to a single
+conversation (or business process). For example if you need to correlation
messages when using web services.
+
+The use of a correlation identifier is key to working with
xref:components:others:tracing.adoc[Distributed Tracing]
+and be useful when using xref:latest@manual::tracer.adoc[Tracer] messages to
log,
+or testing with simulation or canned data such as with the
xref:components::mock-component.adoc[Mock] testing framework.
+
+
+== EIPs using correlation identifiers
Some xref:enterprise-integration-patterns.adoc[EIP] patterns will spin off a
sub message, and in
those cases, Camel will add a correlation id on the
xref:latest@manual:ROOT:exchange.adoc[Exchange] as a property with they key
`Exchange.CORRELATION_ID`, which links back to the source
-xref:latest@manual:ROOT:exchange.adoc[Exchange]. For example the
-xref:split-eip.adoc[Splitter], xref:multicast-eip.adoc[Multicast],
-xref:recipientList-eip.adoc[Recipient List], and xref:wireTap-eip.adoc[Wire
-Tap] EIP does this.
+xref:latest@manual:ROOT:exchange.adoc[Exchange] and its exchange id.
+
+The following EIPs does this:
+
+- xref:enrich-eip.adoc[Enrich]
+- xref:multicast-eip.adoc[Multicast]
+- xref:recipientList-eip.adoc[Recipient List]
+- xref:split-eip.adoc[Split]
+- xref:wireTap-eip.adoc[Wire Tap]
-The following example demonstrates using the Camel JMSMessageID as the
-Correlation Identifier within a request/reply pattern in
-the xref:components::jms-component.adoc[JMS] component
+== Example
-== Samples
+The following example uses a request/reply pattern in
+the xref:components::jms-component.adoc[JMS] component, where correlation
identifiers are automatically handled:
[source,java]
----
from("direct:start")
- .to(ExchangePattern.InOut,
"jms:queue:foo?useMessageIDAsCorrelationID=true")
+ .to(ExchangePattern.InOut, "jms:queue:foo")
.to("mock:result");
----
-And with XML:
+And with XML DSL:
[source,xml]
-------------------------------------------------------------------------------
+----
<route>
<from uri="direct:start"/>
- <to pattern="InOut" uri="jms:queue:foo?useMessageIDAsCorrelationID=true"/>
+ <to pattern="InOut" uri="jms:queue:foo"/>
<to uri="mock:result"/>
</route>
-------------------------------------------------------------------------------
+----
diff --git
a/core/camel-core-engine/src/main/docs/modules/eips/pages/customLoadBalancer-eip.adoc
b/core/camel-core-engine/src/main/docs/modules/eips/pages/customLoadBalancer-eip.adoc
index 16215a2..e5d533a 100644
---
a/core/camel-core-engine/src/main/docs/modules/eips/pages/customLoadBalancer-eip.adoc
+++
b/core/camel-core-engine/src/main/docs/modules/eips/pages/customLoadBalancer-eip.adoc
@@ -5,7 +5,7 @@
:since:
:supportLevel: Stable
-This EIP allows you to use your own Load Balancer implementation
+This EIP allows you to use your own xref:loadBalance-eip.adoc[Load Balancer]
implementation.
// eip options: START
The Custom Load Balancer EIP supports 1 options which are listed below:
@@ -17,8 +17,10 @@ The Custom Load Balancer EIP supports 1 options which are
listed below:
|===
// eip options: END
+== Example
An example using Java DSL:
+
[source,java]
----
from("direct:start")
@@ -28,6 +30,7 @@ from("direct:start")
----
And the same example using XML DSL:
+
[source,xml]
----
<!-- this is the implementation of our custom load balancer -->
@@ -48,19 +51,9 @@ And the same example using XML DSL:
</camelContext>
----
-Notice in the XML DSL above we use `<custom>` which is only available in
*Camel 2.8* onwards. In older releases you would have to do as follows instead:
-[source,xml]
-----
-<loadBalance ref="myBalancer">
- <!-- these are the endpoints to balancer -->
- <to uri="mock:x"/>
- <to uri="mock:y"/>
- <to uri="mock:z"/>
-</loadBalance>
-----
-
To implement a custom load balancer you can extend some support classes such
as `LoadBalancerSupport` and `SimpleLoadBalancerSupport`.
The former supports the asynchronous routing engine, and the latter does not.
Here is an example of a custom load balancer implementation:
+
[source,java]
----
public static class MyLoadBalancer extends LoadBalancerSupport {
diff --git a/docs/user-manual/modules/ROOT/pages/backlog-tracer.adoc
b/docs/user-manual/modules/ROOT/pages/backlog-tracer.adoc
index 2b96698..2de1ebb 100644
--- a/docs/user-manual/modules/ROOT/pages/backlog-tracer.adoc
+++ b/docs/user-manual/modules/ROOT/pages/backlog-tracer.adoc
@@ -1,45 +1,31 @@
-[[BacklogTracer-BacklogTracerInterceptor]]
-= BacklogTracer Interceptor
-
-*Since Camel 2.11*
+[[BacklogTracer-BacklogTracer]]
+= BacklogTracer
Camel supports a backlog tracer interceptor that is used for capturing a
-trace message of each message as they are routed in Camel. +
- The trace message is stored in a backlog queue, which contains the last
+trace message of each message as they are routed in Camel.
+The trace message is stored in a backlog queue, which contains the last
N messages for each node in the routes (by default 10).
-The BacklogTracer is an InterceptStrategy which can be applied to a
-DefaultCamelContext or SpringCamelContext to ensure that there is a
-TracerInterceptor created for every node in the DSL.
-
-You can enable or disable the BacklogTracer's logging dynamically, by
-calling the backlogTracer's `setEnabled` method.
-
-[[BacklogTracer-BacklogTracerDifference]]
== What is the difference between BacklogTracer and Tracer
Camel also provides a xref:tracer.adoc[Tracer] which has similar
capabilities as this backlog tracer. The difference is that the backlog
-tracer is storing +
- a capture of the message in an internal backlog queue. Where as the
-xref:tracer.adoc[Tracer] is event based and logs the messages as they
-happen (or route to another Camel destination). Also the
-xref:tracer.adoc[Tracer] has more fine grained events where it dives
-into xref:{eip-vc}:eips:enterprise-integration-patterns.adoc[EIP]s such as the
-xref:{eip-vc}:eips:choice-eip.adoc[Content Based Router] and traces the
-when/otherwise(s). Though the xref:tracer.adoc[Tracer] has much more
-complicated logic to handle this (there is some edge-cases where this
-may not work). The BacklogTracer allows you to pull the messages from
-the backlog queues on demand. The BacklogTracer works better with JMX
-capable tooling as it is simpler and allow to bulk dump all its traced
-messages in either a POJO or XML format. And there is a Karaf command
-for the BacklogTracer which allows you to control the tracing from a
-Karaf shell.
-
-[[BacklogTracer-Options]]
+tracer is storing a capture of the message in an internal backlog queue.
+
+The xref:tracer.adoc[Tracer] is event based and logs the messages as they
+happen (or route to another Camel destination).
+
+Use the xref:tracer.adoc[Tracer] when all you need is to log the traced
messages
+as they happen.
+
+The backlog tracer allows you to pull the messages from
+the backlog queues on demand. The backlog tracer works better with JMX
+capable tooling as it is simpler, allowing to bulk dump all its traced
+messages in either a POJO or XML format.
+
== Options
-[width="100%",cols="10%,90%",options="header",]
+[width="100%",cols="10%,10%,80%",options="header",]
|===
|Option |Default |Description
@@ -78,7 +64,7 @@ is that the file content has to be read from the file.
[[BacklogTracer-Operations]]
== Operations
-[width="100%",cols="10%,90%",options="header",]
+[width="100%",cols="10%,20%,70%",options="header",]
|===
|Option |Default |Description
@@ -98,8 +84,28 @@ format.
|===
-[[BacklogTracer-Enabling]]
== Enabling
-You would need to enable this using the JMX API.
+You can turn off backlog tracing on `CamelContext`
+
+[source,java]
+----
+camelContext.setBacklogTracing(true);
+----
+
+And in Spring XML
+
+[source,xml]
+----
+<camelContext backlogTrace="true">
+ ...
+</camelContext>
+----
+
+And in Spring Boot you can enable this in the `application.properties` file:
+
+[source,properties]
+----
+camel.springboot.backlog-tracing = true
+----
diff --git a/docs/user-manual/modules/ROOT/pages/tracer.adoc
b/docs/user-manual/modules/ROOT/pages/tracer.adoc
index 9aa1fbc..576d57c 100644
--- a/docs/user-manual/modules/ROOT/pages/tracer.adoc
+++ b/docs/user-manual/modules/ROOT/pages/tracer.adoc
@@ -3,6 +3,8 @@
Camel's tracer is used for logging message details during routing, where
you can see the route path of each message as they happen. Details of the
message is also logged such as the message body.
+TIP: There is an alternative tracer that captures the messages in a
xref:backlog-tracer.adoc[Backlog Tracer].
+
== Formatting
The tracer formats the execution of exchanges to log lines. They are
