JMX Metrics

This page describes the how to retrieve Lenses Agent JMX metrics.

The JMX endpoint is managed by the lenses.jmx.port option. To disable the JMX leave the option empty.

To enable monitoring of the Agent metrics:

LENSES_JMX_OPTS="-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.local.only=false -Djava.rmi.server.hostname=[HOSTNAME]"

To export via Prometheus exporter:

export LENSES_OPTS="-javaagent:/path/to/jmx_exporter/fastdata_agent.jar=9102:/path/to/jmx_exporter/client.yml"

The Agent Docker image (lensesio/lenses) automatically sets up the Prometheus endpoint. You only have to expose the 9102 port to access it.

Setting up the JMX Agent with Basic Auth.

This will be done in two parts. The first part is about setting up the required files that JMX Agent will require and the second is about the options we need to pass to the agent.

Setting up required files

First let’s create a new folder called jmxremote

mkdir -vp /etc/jmxremote

To enable basic auth JMX, first create two files:

• jmxremote.access

• jmxremote.password

JMX Password file

The password file has the credentials that the JMX agent will check during client authentication

cat /etc/jmxremote/jmxremote.password 
admin admin
guest admin

The above code is registering 2 users.

• UserA:

  • username admin

  • password admin

• UserB:

  • username: guest

  • password: admin

JMX Access file

The access file has authorization information, like who is allowed to do what.

cat jmxremote/jmxremote.access 
admin readwrite
guest readonly

In the above code, we can see that the admin user can do read and write operations in JMX, while guest user can only read the JMX content.

Enable JMX with Basic Auth Protection

Now, to enable JMX with basic auth protection, all we need to do is pass the following options in the JRE’s env that will run the Java process you need to protect the jmx.

Let’s assume this java process is Kafka.

Change the permissions on both files so only owner can edit and view them.

chmod -R 0600 /etc/jmxremote
chown -R <user-that-will-run-kafka-name>:<user-that-will-run-kafka-group> /etc/jmxremote/jmxremote.*

If you do not change the permissions to 0600 and to the user that will run the jre process, then JMX will Agent will cause an error complaining that the Process is not the owner of the files that will be used for authentication and authorization.

Finally export the following options in the user’s env which will run Kafka.

export BROKER_JMX_OPTS= "-Dcom.sun.management.jmxremote=true \
  -Dcom.sun.management.jmxremote.authenticate=true \
  -Dcom.sun.management.jmxremote.ssl=false \
  -Dcom.sun.management.jmxremote.local.only=false \
  -Djava.rmi.server.hostname=10.15.3.1 \
  -Dcom.sun.management.jmxremote.rmi.port=9581 \
  -Dcom.sun.management.jmxremote.access.file=/etc/jmxremote/jmxremote.access \
  -Dcom.sun.management.jmxremote.password.file=/etc/jmxremote/jmxremote.password \
  -Dcom.sun.management.jmxremote.port=9581

Secure JMX with TLS Encryption

First setup JMX with basic auth as shown in the Secure JMX: Basic Auth page.

To enable TLS Encryption/Authentication in JMX you need a jks keystore and truststore.

Please note that both JKS Truststore and Keystore should have the same password.

The reason for this is because the javax.net.ssl class will use the password you pass to the Keystore as the keypassword

Let’s assume this java process is Kafka and that you have installed the keystore.jks and truststore.jks under `/etc/certs``

Export the following options in the user’s env which will run Kafka.

export BROKER_JMX_OPTS= "-Dcom.sun.management.jmxremote=true
  -Dcom.sun.management.jmxremote.authenticate=true \
  -Dcom.sun.management.jmxremote.ssl=true \
  -Dcom.sun.management.jmxremote.local.only=false \
  -Djava.rmi.server.hostname=10.15.3.1 \
  -Dcom.sun.management.jmxremote.rmi.port=9581 \
  -Dcom.sun.management.jmxremote.access.file=/etc/jmxremote.access \
  -Dcom.sun.management.jmxremote.password.file=/etc/jmxremote.password \
  -Dcom.sun.management.jmxremote.port=9581 \
  -Djavax.net.ssl.keyStore=/etc/certs/kafka.jks \
  -Djavax.net.ssl.keyStorePassword=somePassword \
  -Djavax.net.ssl.trustStore=/etc/certs/truststore.jks \
  -Djavax.net.ssl.trustStorePassword=somePassword \
  -Dcom.sun.management.jmxremote.registry.ssl=true \
  -Dcom.sun.management.jmxremote.ssl.need.client.auth=true