Activating a component’s JMX interface

This page describes how to enable Java Management Extensions (JMX) monitoring for Liberator, Transformer, and other DataSources.

Overview

The Caplin Management Console (CMC) connects to monitorable components via Java Remote Method Invocation (RMI).

By default, a DataSource’s RMI interface is not enabled and so the DataSource is not available for monitoring. To activate a DataSource’s RMI interface, you define values for the configuration items rmi-registry-port and rmi-client-port.

How you define values for rmi-registry-port and rmi-client-port differs between DataSources. Some DataSources require you to set these configuration items indirectly via macro definitions; other require you to set the configuration items directly.

Liberator

Liberator’s JMX interface is not activated by default. Follow the steps below to activate it:

  1. Run the command below to stop Liberator:

    ./dfw stop Liberator
  2. Run the command below to activate the LiberatorJMX blade:

    ./dfw activate LiberatorJMX
  3. In the file global_config/environment.conf, set Liberator’s Java RMI hostname to the hostname or IP address of Liberator’s host:

    define LIBERATOR${THIS_LEG}_JMX_RMI_SERVER_HOSTNAME     <hostname>
    If you do not set a Java RMI hostname, Java RMI attempts to detect the hostname automatically. In practice, this can often mean the hostname defaults to 'localhost', which causes connectivity problems when CMC is run on a different host to Liberator.
  4. If your architecture requires it, in the file global_config/environment.conf, change the default port numbers for Liberator’s Java RMI ports:

    define LIBERATOR${THIS_LEG}_JMX_RMI_REGISTRY_PORT         ${THIS_LEG}1001
    define LIBERATOR${THIS_LEG}_JMX_RMI_CLIENT_PORT           ${THIS_LEG}2001
  5. Run the command below to restart Liberator:

    ./dfw start Liberator

Transformer

Transformer’s JMX interface is not enabled by default. Follow the steps below to activate it:

  1. Run the command below to stop Transformer:

    ./dfw stop Transformer
  2. Run the Deployment Framework command below to activate the TransformerJMX blade:

    ./dfw activate TransformerJMX
  3. In the file global_config/environment.conf, set Transformer’s Java RMI hostname to the hostname or IP address of Transformer’s host:

    define TRANSFORMER${THIS_LEG}_JMX_RMI_SERVER_HOSTNAME     <hostname>
    If you do not set a Java RMI hostname, Java RMI attempts to detect the hostname automatically. In practice, this can often mean the hostname defaults to 'localhost', which causes connectivity problems when CMC is run on a different host to Transformer.
  4. If your architecture requires it, in the file global_config/environment.conf, change the default port numbers for Transformer’s Java RMI ports:

    define TRANSFORMER${THIS_LEG}_JMX_RMI_REGISTRY_PORT         ${THIS_LEG}1002
    define TRANSFORMER${THIS_LEG}_JMX_RMI_CLIENT_PORT           ${THIS_LEG}2002
  5. Run the command below to restart Transformer:

    ./dfw start Transformer

DataSource adapter blades

Follow the instructions in this section to enable JMX for DataSource adapter blades.

Caplin-supplied C DataSource adapter blades

Caplin-supplied C DataSource adapter blades package their JMX configuration in a JMX blade, which can be activated and deactivated from the command line.

The following Caplin adapters include JMX blades:

  • Caplin TREP adapter

  • Caplin RMDS adapter

The steps for enabling the JMX interface of the above adapters are similar to the steps for enabling the JMX interfaces of Liberator and Transformer, but you override the values for the RMI ports and hostname in the file global_config/overrides/bladename/DataSource/etc/environment.conf.

For example, to enable the JMX interface of the Caplin TREP adapter, follow the steps below:

  1. Stop the adapter:

    ./dfw stop TREPAdapter
  2. Activate the JMX blade for the adapter:

    ./dfw activate TREPAdapterJMX
  3. To change the TREP adapter’s default RMI settings, edit the file global_config/overrides/TREPAdapter/DataSource/etc/environment.conf, and change the values assigned to the following macros:

    • TREPAdapter${THIS_LEG}_JMX_RMI_REGISTRY_PORT

    • TREPAdapter${THIS_LEG}_JMX_RMI_CLIENT_PORT

    • TREPAdapter${THIS_LEG}_JMX_RMI_SERVER_HOSTNAME

  4. Restart the adapter:

    ./dfw start TREPAdapter

Custom-written C DataSource adapter blades

To enable the JMX interface of a C DataSource that does not include a JMX configuration blade, add the following configuration items to the file global_config/overrides/bladename/etc/datasource-overrides.conf:

# RMI registry port
rmi-registry-port <port>

# RMI client port
rmi-client-port <port>

# RMI hostname
jvm-options -Djava.rmi.server.hostname=<hostname>

For more information on the configuration items above, see the links below:

Java DataSource adapter blades

To enable the JMX interface of a Java DataSource, add the following lines to the file global_config/overrides/bladename/etc/datasource-overrides.conf:

# RMI registry port
rmi-registry-port <port>

# RMI client port
rmi-client-port <port>

In the adapter’s DataSource/bin/start-jar.sh file, add the following system property assignment to the java command that runs the Java DataSource’s jar file:

java -Djava.rmi.server.hostname=<hostname> ...

For more information on the configuration items above, see the links below: