JMX Importer

The JMX Importer enables fetching data out of JMX MBeans and create metrics out of these via configuration. This section contains information how to set things up.

Dependency

Add the JMX Importer dependency to your build:

sbt
libraryDependencies += Cinnamon.library.jmxImporter
Maven
<dependency>
    <groupId>com.lightbend.cinnamon</groupId>
    <artifactId>cinnamon-jmx-importer_2.12</artifactId>
    <version>2.7.3</version>
</dependency>
Gradle
dependencies {
    compile group: 'com.lightbend.cinnamon', name: 'cinnamon-jmx-importer_2.12', version: '2.7.3'
}

Configuration

To configure the JMX Importer we must, apart from defining its context cinnamon.jmx-importer, provide settings for beans.

Required

No required configuration is needed for the importer to load, but without any beans definition there won’t be any metrics created.

Reference
cinnamon {
  jmx-importer {
    identity {
      domain {
        category = "domains"
        key = "domain"
      }

      type {
        category = "types"
        key = "type"
      }

      name {
        category = "names"
        key = "name"
      }

      attribute {
        category = "attributes"
        key = "attribute"
      }
    }

    descriptor {
      group-name = "metrics"
    }
  }
}

Note: These settings are defined in the reference.conf. You only need to specify any of these settings when you want to override the defaults.

The beans setting

The beans setting is where we define what JMX beans to retrieve and what attributes of them that should be used to create metrics. This section consists of a couple of subparts:

  • query: query used to retrieve the beans from JMX
  • suppress-log-warnings: indicates if any warnings, when getting JMX info for this bean, should be suppressed - optional and defaults to false
  • attributes: attributes that should be converted to metrics. Each attribute must contain the following:
    • attribute: name of the attribute
    • type: type of metrics that should be generated

The JMX Importer currently supports two types of metrics:

  • GAUGE_LONG: generates a com.lightbend.cinnamon.metric.ProvidingGaugeLong.
  • GAUGE_DOUBLE: generates a com.lightbend.cinnamon.metric.ProvidingGaugeDouble.

Example configurations

Let us take a look at some examples to get a better idea of what things can look like.

Simple

A simple configuration with which we get all beans in the domain someDomain, with type *, and name *. * represents wildcard, i.e. match everything in that context. Each bean matching is expected to have the attribute SomeAttribute and the type for this attribute is a long.

cinnamon.jmx-importer {
  beans = [
    {
      query = "someDomain:type=*,name=*",
      suppress-log-warnings = yes,
      attributes = [
        {
          attribute = "SomeAttribute",
          metric-type = "GAUGE_LONG"
        }
      ]
    }
  ]
}

JVM

An example of how to use the JMX Producer to generate some JVM related metrics in Cinnamon.

cinnamon.jmx-importer {
  beans = [
    {
      query = "java.lang:type=GarbageCollector,name=PS MarkSweep"
      attributes = [
        {
          attribute = "CollectionCount",
          metric-type = "GAUGE_LONG"
        },
        {
          attribute = "CollectionTime",
          metric-type = "GAUGE_LONG"
        }
      ]
    },
    {
      query = "java.lang:type=GarbageCollector,name=PS Scavenge"
      attributes = [
        {
          attribute = "CollectionCount",
          metric-type = "GAUGE_LONG"
        }
      ]
    },
    {
      query = "java.lang:type=OperatingSystem"
      attributes = [
        {
          attribute = "SystemCpuLoad",
          metric-type = "GAUGE_DOUBLE"
        }
      ]
    }
  ]
}

The above configuration will generate four unique metrics in Cinnamon.

Output format

The output format depends on how metrics are reported, i.e. what reporter(s) that have been configured to be used. Whatever reporter used, the idea is to mimic the layout of the MBeans explorer in Java Mission Control. As an example, using the JVM configuration here above would generate the following format:

StatsD

Metrics output:

servers.<your server>.apps.<your app>.metrics.jmx.domains.java_lang.types.GarbageCollector.names.PS_MarkSweep.attributes.CollectionCount.CollectionCount
servers.<your server>.apps.<your app>.metrics.jmx.domains.java_lang.types.GarbageCollector.names.PS_MarkSweep.attributes.CollectionTime.CollectionTime
servers.<your server>.apps.<your app>.metrics.jmx.domains.java_lang.types.GarbageCollector.names.PS_Scavange.attributes.CollectionCount.CollectionCount
servers.<your server>.apps.<your app>.metrics.jmx.domains.java_lang.types.OperatingSystem.attributes.SystemCpuLoad.SystemCpuLoad

Elasticsearch

Metric output for one of the configured beans:

{
  ... some metadata
  "application" : <your app>,
  "attribute" : "SystemCpuLoad",
  "domain" : "java.lang",
  "host" : <your host>,
  "metric" : "attributes.SystemCpuLoad",
  "type" : "OperatingSystem"
}