[
https://issues.apache.org/jira/browse/ARTEMIS-3243?focusedWorklogId=633156&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-633156
]
ASF GitHub Bot logged work on ARTEMIS-3243:
-------------------------------------------
Author: ASF GitHub Bot
Created on: 03/Aug/21 20:37
Start Date: 03/Aug/21 20:37
Worklog Time Spent: 10m
Work Description: clebertsuconic commented on a change in pull request
#3633:
URL: https://github.com/apache/activemq-artemis/pull/3633#discussion_r682084219
##########
File path: docs/user-manual/en/amqp-broker-connections.md
##########
@@ -32,121 +32,145 @@ To define an AMQP broker connection, add an
`<amqp-connection>` element within t
- `password`: Password with which to connect to the endpoint (this is an
optional argument)
- `retry-interval`: Time, in milliseconds to wait before retrying a connection
after an error. The default value is `5000`.
- `reconnect-attempts`: default is -1 meaning infinite
-- `auto-start` : Should the broker connection start automatically with the
broker. Default is `true`. If false you need to call a management operation to
start it.
+- `auto-start` : Should the broker connection start automatically with the
broker. Default is `true`. If false it is necessary to call a management
operation to start it.
-*Notice:* If you disable auto-start on the broker connection, the start of the
broker connection will only happen after the management method
`startBrokerConnection(connectionName)` is called on the ServerController.
+*Notice:* If auto-start is disabled on the broker connection, the start of the
broker connection will only happen after the management method
`startBrokerConnection(connectionName)` is called on the ServerController.
-*Important*: The target endpoint needs permission for all operations that you
configure. Therefore, If you are using a security manager, ensure that you
perform the configured operations as a user with sufficient permissions.
+*Important*: The target endpoint needs permission for all operations that
configured. Therefore, If a security manager is being used, ensure to perform
the configured operations with a user with sufficient permissions.
# AMQP Server Connection Operations
-The following types of operations are supported on a AMQP server connection:
+The following types of operations are supported on an AMQP server connection:
+* Mirrors
+ * The broker uses an AMQP connection to another broker and duplicates
messages and sends acknowledgements over the wire.
* Senders
- * Messages received on specific queues are transferred to another endpoint
+ * Messages received on specific queues are transferred to another endpoint.
* Receivers
- * The broker pulls messages from another endpoint
+ * The broker pulls messages from another endpoint.
* Peers
- * The broker creates both senders and receivers on another endpoint that
knows how to handle them. Currently, this is implemented by Apache Qpid
Dispatch.
-* Mirrors
- * The broker uses an AMQP connection to another broker and duplicate
messages and sends acknowledgements over the wire.
+ * The broker creates both senders and receivers on another endpoint that
knows how to handle them. This is currently implemented by Apache Qpid Dispatch.
+
+# Reconnecting and Failover
-## Senders and Receivers
-It is possible to connect an ActiveMQ Artemis broker to another AMQP endpoint
simply by creating a sender or receiver broker connection element.
+It is possible to determine how reconnection will happen on a broker
connection.
-For a `sender`, the broker creates a message consumer on a queue that sends
messages to another AMQP endpoint.
+These are the attributes are available on amqp-connection XML element:
+- reconnect-attempts: default as -1 (infinite). How many attempts will be done
after a failed connection
+- retry-interval: default as 5000, in milliseconds, the wait between each
retry in connections.
-For a `receiver`, the broker creates a message producer on an address that
receives messages from another AMQP endpoint.
+It is also possible to specify alternate hosts on a broker connection by
appending a comma separated list after a # at the end of the URI.
+The broker connection would keep trying on the alternate list until one of the
targets is available to connect. Example:
-Both elements work like a message bridge. However, there is no additional
overhead required to process messages. Senders and receivers behave just like
any other consumer or producer in ActiveMQ Artemis.
+
+Figure 2. Broker Connection Disaster and Recovery.
-You can configure senders or receivers for specific queues. You can also match
senders and receivers to specific addresses or _sets_ of addresses, using
wildcard expressions. When configuring a sender or receiver, you can set the
following properties:
+The previous example portrays a case of connection failure towards ServerA.
The system would try to connect between serverA, backupA, and backupB until it
successfully connects to any of these nodes.
-- `address-match`: Match the sender or receiver to a specific address or
__set__ of addresses, using a wildcard expression
-- `queue-name`: Configure the sender or receiver for a specific queue
+## Mirroring
+This is probably the main use case for Broker Connections and the main reason
broker connections were developed in the first place.
+The idea of mirroring is to send every event that happened on a broker towards
another broker, without blocking any operations from producers and consumers as
fast as possible.
+It can be used for Disaster and Recovery, and depending on the requirements
even for failing over the data.
-Some examples are shown below.
+The following events are sent through mirroring:
-Using address expressions:
-```xml
-<broker-connections>
- <amqp-connection uri="tcp://MY_HOST:MY_PORT" name="my-broker">
- <sender address-match="queues.#"/>
- <!-- notice the local queues for remotequeues.# need to be created on
this broker -->
- <receiver address-match="remotequeues.#"/>
- </amqp-connection>
-</broker-connections>
+* Message sending
+ * Messages sent in one broker will be "replicated" to the target broker.
+* Message acknowledgement
+ * Messages removed through acks in one broker will be sent towards the
target broker.
+ * Notice if the message is pending on a consumer on the target mirror, the
ack will not succeed and the message might be delivered on both ends.
+* Queue and address creation.
+* Queue and address deletion.
-<addresses>
- <address name="remotequeues.A">
- <anycast>
- <queue name="remoteQueueA"/>
- </anycast>
- </address>
- <address name="queues.B">
- <anycast>
- <queue name="localQueueB"/>
- </anycast>
- </address>
-</addresses>
-```
-Using queue names:
+Add a `<mirror>` element within the `<amqp-connection>` element to configure
it.
+
+### Mirror configuration:
+
+The following optional arguments can be utilized:
+
+* `queue-removal`: Specifies whether a queue- or address-removal event is
sent. The default value is `true`.
+* `message-acknowledgements`: Specifies whether message acknowledgements are
sent. The default value is `true`.
+* `queue-creation`: Specifies whether a queue- or address-creation event is
sent. The default value is `true`.
+
+An example of a mirror configuration is shown below:
```xml
<broker-connections>
- <amqp-connection uri="tcp://MY_HOST:MY_PORT" name="my-broker">
- <receiver queue-name="remoteQueueA"/>
- <sender queue-name="localQueueB"/>
- </amqp-connection>
+ <amqp-connection uri="tcp://MY_HOST:MY_PORT" name="my-mirror">
+ <mirror queue-removal="true" queue-creation="true"
message-acknowledgements="true" source-mirror-address="myLocalSNFMirrorQueue"/>
+ </amqp-connection>
</broker-connections>
+```
-<addresses>
- <address name="remotequeues.A">
- <anycast>
- <queue name="remoteQueueA"/>
- </anycast>
- </address>
- <address name="queues.B">
- <anycast>
- <queue name="localQueueB"/>
- </anycast>
- </address>
-</addresses>
+
+### Store and Forward Queue
+
+Mirror events are always stored on a local queue prefixed as
"$ACTIVEMQ_ARTEMIS_MIRROR_" concatenated with broker connection's name.
+
+So, in the following configuration mirror events will be stored on a queue
named "$ACTIVEMQ_ARTEMIS_MIRROR_my-mirror".
+
+```xml
+<broker-connection>
+ <amqp-connection uri="tcp://brokerB:5672" name="brokerB">
+ <mirror/>
+ </amqp-connection>
+</broker-connection>
Review comment:
I did not commit the suggestion by I imported the changes manually..
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
Issue Time Tracking
-------------------
Worklog Id: (was: 633156)
Time Spent: 35.5h (was: 35h 20m)
> Enhance AMQP Mirror support with dual mirror
> --------------------------------------------
>
> Key: ARTEMIS-3243
> URL: https://issues.apache.org/jira/browse/ARTEMIS-3243
> Project: ActiveMQ Artemis
> Issue Type: Bug
> Affects Versions: 2.17.0
> Reporter: Clebert Suconic
> Assignee: Clebert Suconic
> Priority: Major
> Fix For: 2.18.0
>
> Time Spent: 35.5h
> Remaining Estimate: 0h
>
> at the current Mirror version, we can only mirror into a single direction.
> With this enhancement the two (or more brokers) would be connected to each
> other, each one having its own ID, and each one would send updates to the
> other broker.
> The outcome is that if you just transferred producers and consumers from one
> broker into the other, the fallback would be automatic and simple. No need to
> disable and enable mirror options.
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
