• EnglishEspañol日本語한국어Português
  • Inicia sesiónComenzar ahora

JMX monitoring integration

Our JMX integration allows users to monitor any application that exposes metrics with JMX. The integration includes a default collection file. It collects key metrics from the JVM. The collected metrics vary by app server and include measurements of thread pools, HTTP sessions, and transactions.

Read on to install the integration and to see what data we collect.


If you're not running JMX in Kubernetes or ECS environments, we recommend our guided install. Our guided install uses our infrastructure agent and our CLI to set up the JMX integration. It also finds other applications and log sources in your environment. Then, it recommends which ones you should instrument. The guided install works with most setups. But if it doesn't suit your needs, there are other install options below.

Ready to get started? Click the relevant button, depending on which data center region you use. When you're done with the install, return to this document to review the configuration options.

Guided install, US region

For a more permanent and scalable solution, we recommend the standard manual install of the agent. Keep reading for how to do that.


This integration doesn't automatically update. For best results, regularly update the integration package and the infrastructure agent.

Configuration options

For the standard on-host installation, this integration comes with a YAML config file, jmx-config.yml. This configuration is where you can place required login credentials and configure how data is collected. Which options you change depends on your setup and preferences. It comes with a sample config file jmx-config.yml.sample that you can copy and edit.

Specific settings related to JMX are defined using the env section of the configuration file. These settings control the connection to your JMX instance as well as other security settings and features. The list of valid settings is described in the next section of this document.

Metrics collection files

The metrics collection definition files are structured YAML files which tell the integration what metrics to collect.

This is the default JVM metrics collection file: /etc/newrelic-infra/integrations.d/jvm-metrics.yml


You can write different collection files to ease organization and maintenance. See configuration file for an example.

Collection configuration using Kubernetes annotations

You can use Kubernetes annotations to provide collection configuration. To achieve this, you need to deploy a configMap into the Kubernetes cluster that will create the configuration file for the nri-jmx application.

In this configuration file you need to specify the command for container auto-discovery, which will allow you to use placeholders in the integration configuration, including Kubernetes annotations.

Example of a configMap to monitor JVM in a Tomcat application:

Next, use annotations to define collection configuration. For example, here's a Tomcat deployment with annotations:

apiVersion: apps/v1
kind: Deployment
name: tomcat-deployment
app: java
replicas: 1
app: java
newrelic.config: >-
"collect": [
"domain": "java.lang",
"event_type": "JVMSample",
"beans": [
"query": "type=GarbageCollector,name=*",
"attributes": [
"query": "type=Memory",
"attributes": [
"query": "type=Threading",
"attributes": [
"query": "type=ClassLoading",
"attributes": [
"query": "type=Compilation",
"attributes": [
app: java
- name: tomcat
image: tomcat:10.0.12
- containerPort: 9999
value: '-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9999 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false'

Custom connectors

JMX allows the use of custom connectors to communicate with the application. In order to use a custom connector, you have to include the custom connectors in the nrjmx classpath.

By default, the sub-folder connectors is in the classpath. If this folder doen't exist, create it under the folder where nrjmx is installed.

For example, to add support for JBoss, create a folder named connectors under the default (Linux) library path /usr/lib/nrjmx/ (/usr/lib/nrjmx/connectors/) and copy the custom connector jar ($JBOSS_HOME/bin/client/jboss-cli-client.jar) into it. You can now execute JMX queries against JBoss.

Example configurations

Example file configurations for an on-host install:

For more about the general structure of on-host integration configuration, see Configuration.

Naming your data

We send and store metrics in the form of samples. This is a list of key-value pairs that include metric data and metadata. Each sample is stored as an event in our database.

You are responsible for creating and naming the JMX data reported to New Relic. For this reason, New Relic strongly recommends following these conventions when naming your event types. To ensure you have a consistent naming scheme:

  • Use camel case.
  • Use a name that clearly identifies what data it contains.

Example: MyorgApplicationSample

Recommendation: Use the same naming scheme for similar metrics across different applications.

Metric data

The metrics show metadata for the MBean they are collecting from. You can use this metadata in NRQL queries to filter and facet the data so that the query returns only the data for the desired beans. You can also use it to identify the metrics, as the metric name may not be unique among all beans.

Each event contains the following metadata:




The JMX domain name for these metrics.


The JMX domain name for these metrics with the entity type domain: prepended.


The JMX host the metrics are being collected from.


The query used to collect these metrics.


The bean whose attributes these metrics were collected from.


For each key in the bean name, an attribute is added to the metric set called key:<mbean_key> with the value of the bean's key.

Example NRQL query

Here's an example of NRQL query taking advantage of metadata monitor all the collected JVM garbage collectors:

SELECT latest(CollectionTime)
FACET `key:name`
WHERE `key:type` = 'GarbageCollector'

Metrics data attributes

The JMX integration collects these metric data attributes:




The total Java heap memory used.


The total Java heap memory committed to be used.


The initial Java heap memory allocated.


The maximum Java heap memory available.


The total Java non-heap memory used.


The total Java non-heap memory committed to be used.


The initial Java non-heap memory allocated.


The maximum Java non-heap memory available.


The number of live threads.


The total number of garbage collections that have occurred.


The approximate accumulated garbage collection time elapsed.

Inventory data

The JMX integration captures the configuration parameters of the JMX integration. The data is available on the Inventory page, under the config/jmx source. For more about inventory data, see Understand integration data.


Troubleshooting tips:

Check the source code

This integration is open source software. That means you can browse its source code and send improvements, or create your own fork and build it.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.