Skip to content

Toro Cloud Dev Center


Using a remote ActiveMQ instance as the broker

By default, Martini ships with a pre-configured embedded instance of ActiveMQ. However, for production instances processing large volumes of messages, it is recommended for Martini to be paired with a standalone instance of ActiveMQ instead. This page will guide you through configuring your own remote ActiveMQ server.

Prerequisites

You must have your ActiveMQ instance installed and deployed on your machine. If you would like to deploy more than one instance of ActiveMQ, then you can follow TORO's guide on setting up ActiveMQ in a master-slave setup.

Procedure

  1. Start the remote ActiveMQ instance if it's not already running. You can do this by running ./activemq start in Unix or bin\activemq start in Windows.

    start versus console

    ActiveMQ has start and console commands which can both be used to start the broker instance. The difference between these commands is that start runs the process in the background while console runs the process in the foreground, printing application logs in real time; therefore to navigate away from the process launched by the console command, you will either need to start a new session or kill the process.

  2. Configure the broker connection properties.

    Martini uses the broker connection properties defined in the application.properties file. The following properties need to be configured to connect to a remote ActiveMQ broker:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    # Refers to the file name of the broker configuration to be used.
    # To connect to a remote ActiveMQ instance, set this property's value to 'activemq-external'.
    jms.configuration-file=activemq-external
    
    # This property must be set if you require durable subscribers on topics.
    # The value of this property must be unique among clients connected to the ActiveMQ instance.
    jms.client-id=toroMartini
    
    # The prefix added to mitigate overlapping JMS destinations.
    # This property usually has the same value as jms.client-id but can be same among clients to share destinations
    jms.destination-prefix=toroMartini
    
    # The URL of the remote broker.
    activemq.uri=tcp://<activemq-ip-address>:61616?closeAsync=false
    

    For Runtime Edition subscribers, editing application properties is typically done via manually modifying the <martini-home>/data/override.properties file.

  3. Restart Martini to let the changes take effect.

  4. Verify connection establishment.

    To ensure that Martini was able to connect to ActiveMQ successfully, go to the Connections tab of the ActiveMQ instance's web console. You should see an entry on the Connector openwire section whose name is equivalent to the value of the configured jms.client-id property.

    Verifying ActiveMQ instance connections

    Broker menu

    The Broker menu will disappear from the Martini Runtime Admin UI (available in the Martini Runtime Edition) once Martini gets configured to run with a remote ActiveMQ instance instead. To view broker statistics, you would need to use the ActiveMQ web console.

  5. Verify destinations.

    In the ActiveMQ web console, open the Queues or Topics tab. You should be able to see destinations named {jmsPrefix}.io.toro.martini.Tracker and {jmsPrefix}.io.toro.martini.Monitor where {jmsPrefix} is defined using the property jms.destination-prefix.

    Checking queues present in the ActiveMQ web console

    Checking topics present in the ActiveMQ web console

  6. Verify message enqueuing.

    Martini uses brokers in conjunction with Solr to ensure Tracker and the invoke monitor index data concurrently. This means you can invoke any service and the configured broker (in this case, ActiveMQ) should be able to pick up system messages from Tracker and Monitor.

    To verify if messages do get through to ActiveMQ:

    1. Open the ActiveMQ web console.
    2. Invoke any service; you can use services such as HelloYouService.gloop from the examples package.
    3. After invoking, refresh the ActiveMQ page and you should see the Messages Enqueued property of Tracker and invoke monitor destinations incremented.

    If Tracker's Message Enqueued property did not increment, it is possible that HTTP tracking is disabled. If it's invoke monitor however, and you're using the Runtime Edition, it is possible that monitoring is not enabled.

    Verifying message enqueueing

    And that's it! You have now successfully configured Martini with a remote instance of ActiveMQ.