Enable JMXTrans Agent

By default, Pulse uses PulseJMX to collect JMX metrics from services such as HiveServer2, Impala, ResourceManager, etc.

In some environments, you might encounter JMX port conflicts when multiple JVM processes try to bind to the same static port.

If you face these conflicts, you can replace PulseJMX with JMXTrans-Agent for metrics collection.

Background

PulseJMX relies on a statically assigned JMX port, such as:

-Dcom.sun.management.jmxremote.port=8008

• In certain setups—such as Hadoop MapReduce running in local mode—multiple JVM processes run on the same host.
• Each process tries to bind to the same port (for example, 8008), which causes port binding errors and prevents metrics collection.
• Dynamic port assignment (for example, -Dcom.sun.management.jmxremote.port=0) is not supported by PulseJMX because it requires a known port to collect data.

Alternative: Use JMXTrans-Agent

If port conflicts occur, use JMXTrans-Agent instead of PulseJMX.

JMXTrans-Agent is a lightweight Java agent that runs inside the JVM and sends JMX metrics directly to VictoriaMetrics without using any external ports.

Key Benefits:

• No port conflicts — metrics are collected in-process.
• Simple setup — no need for fixed JMX ports.
• Direct export — sends metrics straight to VictoriaMetrics.
• Works reliably in multi-process environments.

How to Enable?

To use the JMXTrans Agent, complete the following steps to enable JMX metrics collection.

Disable the existing PulseJMX Agent

To disable the PulseJMX agent, update the configuration as follows:

1. Add or update the following setting:
   • For Docker-based deployment: Edit the override.yml file on the Pulse node.
   • For Kubernetes-based deployment: In the Admin UI, on the Home page, select the configured cluster → Configuration tab, and update the VARs YAML section.

agent_enabled:

  pulsejmx: false

2. Reconfigure the cluster to apply the changes.
3. Verify that the pulsejmx agent is no longer running.

Load the JMXTrans Java Agent

When the Hydra Agent is deployed (via SSH or Parcel), it automatically copies the JMXTrans Agent JAR and configuration files for all enabled services to the Hadoop nodes, located in /opt/acceldata/jmx/config/enabled/.

To collect JMX metrics for any service using the JMXTrans Agent, the Java agent must be loaded into the JVM process of that service.

Add the following line to the JAVA_OPTS of the service for which you want to enable JMX metrics collection in the Ambari UI:

export SERVER_JVMFLAGS="$SERVER_JVMFLAGS -javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_zookeeper_server.xml"

Example:

To collect ZooKeeper metrics, add the following line to the JAVA_OPTS for ZooKeeper:

export SERVER_JVMFLAGS="$SERVER_JVMFLAGS -javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_zookeeper_server.xml"

All XML configuration files for supported services are located at: /opt/acceldata/jmx/config/enabled.

Update the Java Options for Services Using JMX Agent

You can update the Java options for the services through the Ambari UI.

Below are detailed, service-wise details for all services supported by the JMX agent.

Cruise Control

1. In the Ambari UI, go to Kafka → Advanced → cruise-control-env template.
2. Add the following line at the end of the template:

export KAFKA_OPTS="$KAFKA_OPTS -javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_cruise_control.xml"

Cruise Control 3

1. In the Ambari UI, go to Kafka3 → Advanced → cruise-control3-env template.
2. Add the following line at the end of the template:

export KAFKA_OPTS="$KAFKA_OPTS -javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_cruise_control3.xml

Hive Metastore

1. In the Ambari UI, go to Hive → Advanced → hive-env template
2. Add the following line inside the section: if [ "$SERVICE" = "metastore" ].

export HADOOP_OPTS="$HADOOP_OPTS -javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_hive_server.xml"

Hive Server

1. In the Ambari UI, go to Hive → Advanced → hive-env template.
2. Add the following line inside the section: if [ "$SERVICE" = "hiveserver2" ].

export HADOOP_OPTS="$HADOOP_OPTS -javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_hive_metastore.xml"

Kafka

If Kafka Connect is NOT enabled:

1. Go to Kafka → Advanced → kafka-env template
2. Add the following line at the end:

export KAFKA_OPTS="$KAFKA_OPTS -javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_kafka.xml"

If Kafka Connect is enabled:

Add the following snippet at the end of the kafka-env template:

AGENT_PATH="/opt/acceldata/jmx/lib/jmxtrans-agent.jar"

if [[ "$KAFKA_OPTS" != *"$AGENT_PATH"* ]]; then

    CURRENT_CMD_STRING=$(ps -p $$ -o args=)

    if [[ "$CURRENT_CMD_STRING" == *"kafka-connect"* ]]; then

        export KAFKA_OPTS="$KAFKA_OPTS -javaagent:$AGENT_PATH=/opt/acceldata/jmx/config/enabled/vm_kafka3_connect.xml"

    elif [[ "$CURRENT_CMD_STRING" == *"kafka start"* ]] || [[ "$CURRENT_CMD_STRING" == *"kafka-server-start"* ]]; then

        export KAFKA_OPTS="$KAFKA_OPTS -javaagent:$AGENT_PATH=/opt/acceldata/jmx/config/enabled/vm_kafka3.xml"

    fi

fi

Kafka 3

If Kafka Connect is NOT enabled:

1. Go to Kafka3 → Advanced → kafka-env template
2. Add the following line at the end:

export KAFKA_OPTS="$KAFKA_OPTS -javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_kafka3.xml"

If Kafka Connect is enabled:

Add the following snippet:

AGENT_PATH="/opt/acceldata/jmx/lib/jmxtrans-agent.jar"

if [[ "$KAFKA_OPTS" != *"$AGENT_PATH"* ]]; then

    CURRENT_CMD_STRING=$(ps -p $$ -o args=)

    if [[ "$CURRENT_CMD_STRING" == *"kafka-connect"* ]]; then

        export KAFKA_OPTS="$KAFKA_OPTS -javaagent:$AGENT_PATH=/opt/acceldata/jmx/config/enabled/vm_kafka3_connect.xml"

    elif [[ "$CURRENT_CMD_STRING" == *"kafka3 start"* ]] || [[ "$CURRENT_CMD_STRING" == *"kafka-server-start"* ]]; then

        export KAFKA_OPTS="$KAFKA_OPTS -javaagent:$AGENT_PATH=/opt/acceldata/jmx/config/enabled/vm_kafka3.xml"

    fi

fi

Kafka Connect

1. Go to Kafka → Advanced → kafka-env template
2. Add the following snippet at the end:

AGENT_PATH="/opt/acceldata/jmx/lib/jmxtrans-agent.jar"

if [[ "$KAFKA_OPTS" != *"$AGENT_PATH"* ]]; then

    CURRENT_CMD_STRING=$(ps -p $$ -o args=)

    if [[ "$CURRENT_CMD_STRING" == *"kafka-connect"* ]]; then

        export KAFKA_OPTS="$KAFKA_OPTS -javaagent:$AGENT_PATH=/opt/acceldata/jmx/config/enabled/vm_kafka3_connect.xml"

    elif [[ "$CURRENT_CMD_STRING" == *"kafka start"* ]] || [[ "$CURRENT_CMD_STRING" == *"kafka-server-start"* ]]; then

        export KAFKA_OPTS="$KAFKA_OPTS -javaagent:$AGENT_PATH=/opt/acceldata/jmx/config/enabled/vm_kafka3.xml"

    fi

fi

Kafka3 Connect

1. Go to Kafka3 → Advanced → kafka3-env template.
2. Add the following snippet at the end:

AGENT_PATH="/opt/acceldata/jmx/lib/jmxtrans-agent.jar"

if [[ "$KAFKA_OPTS" != *"$AGENT_PATH"* ]]; then

    CURRENT_CMD_STRING=$(ps -p $$ -o args=)

    if [[ "$CURRENT_CMD_STRING" == *"kafka-connect"* ]]; then

        export KAFKA_OPTS="$KAFKA_OPTS -javaagent:$AGENT_PATH=/opt/acceldata/jmx/config/enabled/vm_kafka3_connect.xml"

    elif [[ "$CURRENT_CMD_STRING" == *"kafka3 start"* ]] || [[ "$CURRENT_CMD_STRING" == *"kafka-server-start"* ]]; then

        export KAFKA_OPTS="$KAFKA_OPTS -javaagent:$AGENT_PATH=/opt/acceldata/jmx/config/enabled/vm_kafka3.xml"

    fi

fi

Kafka MirrorMaker2

1. Go to Kafka → Advanced → kafka-mirrormaker2-env
2. Add the following line at the end:

export KAFKA_OPTS="$KAFKA_OPTS -javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_mm2.xml"

Kafka3 MirrorMaker2

1. Go to Kafka3 → Advanced → kafka-mirrormaker2-env
2. Add the following line at the end:

export KAFKA_OPTS="$KAFKA_OPTS -javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_kafka3mm2.xml"

Pinot Broker

1. Go to Pinot Broker → Java Virtual Machine (JVM) Options
2. Add the following line at the end:

export JAVA_OPTS="$JAVA_OPTS -javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_pinot_broker.xml"

Pinot Controller

1. Go to Pinot Controller → Java Virtual Machine (JVM) Options
2. Add the following line at the end:

export JAVA_OPTS="$JAVA_OPTS -javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_pinot_controller.xml"

Pinot Server

1. Go to Pinot Server → Java Virtual Machine (JVM) Options
2. Add the following line at the end:

export JAVA_OPTS="$JAVA_OPTS -javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_pinot_server.xml"

Ranger (Admin, Tagsync, Usersync)

1. Go to Ranger → Advanced → ranger-env template

Ranger Admin

Add the line below in the {% if is_ranger_admin_host %} section:

export JAVA_OPTS="${JAVA_OPTS} -javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_ranger_admin.xml"

Ranger Tagsync

For Tagsync, add the below line in the {% if is_ranger_tagsync_host %} section:

export JAVA_OPTS="${JAVA_OPTS} -javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_ranger_tagsync.xml"

Ranger Usersync

For Usersync, add the line below in the {% if is_ranger_usersync_host %} section:

export JAVA_OPTS=" ${JAVA_OPTS} -javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_ranger_usersync.xml"

Schema Registry

1. Go to Schema Registry → registry-env template
2. Add the following line at the end:

export REGISTRY_OPTS="$REGISTRY_OPTS -javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_schema_registry.xml"

Trino (Coordinator and Worker)

1. Go to Trino → JVM Config file
2. Add the following snippet at the end:

{% if hostname == coordinator_host %}

-javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_trino_coordinator.xml

{% else %}

-javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_trino_worker.xml

{% endif %}

Zookeeper

1. Go to Zookeeper → Advanced → zookeeper-env template
2. Add the following line at the end:

export SERVER_JVMFLAGS="$SERVER_JVMFLAGS -javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_zookeeper_server.xml"

Zeppelin Master

1. Go to Zeppelin → zeppelin_env_content
2. Add the following line at the end:

export ZEPPELIN_JAVA_OPTS="$ZEPPELIN_JAVA_OPTS -javaagent:/opt/acceldata/jmx/lib/jmxtrans-agent.jar=/opt/acceldata/jmx/config/enabled/vm_zeppelin_master.xml"

Verify Metrics Collection

After a restart, the Java agent automatically starts sending metrics to VictoriaMetrics based on the configured polling interval.