Skip to main content

airframe-jmx: JMX Application Monitor

airframe-jmx enables exposing application information through JMX so that you can check the running state of an application outside JVM. For example, you can use jconsole program to access JMX parameters.

JMX already provides various JVM metrics (e.g., heap memory usage, GC statistics, etc.). DataDog provides a handy way to collect JMX metrics:

For analyzing application behavior for longer ranges (5 minute or more), we recommend using Treasure Data along with DataDog:

JMX -> fluentd -> DataDog   (For real-time monitoring)
               -> Treasure Data -> Presto SQL (Doing metric-driven actions with SQL queries)

Usage​

Maven Central

libraryDependencies += "org.wvlet.airframe" %% "airframe-jmx" % "(version)"

Usage is simple: Add @JMX annotation to variables or methods you want to see in JMX.

Registering JMX parameters​

import wvlet.airframe.jmx._

@JMX(description = "A example MBean object")
class SampleMBean {
  @JMX(description = "free memory size")
  def freeMemory: Long = {
    Runtime.getRuntime.freeMemory()
  }
}

// Register the MBean to make it visible from JMX interface
val mbean = new SampleMBean
JMXAgent.defaultAgent.register[SampleMBean](mbean)

Nested parameters​

To report nested parameters, add @JMX to parameters as well:

class NestedMBean {
  @JMX(description = "nested stat")
  def stat: Stat = {
    Stat(Random.nextInt(10), "nested JMX bean")
  }
}

case class Stat(@JMX count: Int, @JMX state: String)

In this example, stat.count and stat.state will be reported.

Specify parameter names explicitly​

Parameter names are automatically generated but also can be specified explicitly.

@JMX(description = "A example MBean object")
class NamedMBean {
  @JMX(name = "memory.free", description = "free memory size")
  def freeMemory: Long = {
    Runtime.getRuntime.freeMemory()
  }
}

Launching JMX Registry​

You can launch JMXRegistry (e.g., on port 7199) by setting these JVM parameters:

-Dcom.sun.management.jmxremote
-Dcom.sun.management.jmxremote.port=7199
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.local.only=false
-Dcom.sun.management.jmxremote.ssl=false

For convenience, you can start JMXRegistry inside your program:

wvlet.airframe.jmx.JMXAgent.start(registryPort=7199)

Using airframe-jmx with Airframe DI​

import wvlet.airframe._
import wvlet.airframe.jmx._

case class MyAppStats(
  @JMX(description = "application access count")
  accessCount:Int
)

@JMX(description = "My application")
trait MyApp { self =>

  bind[JMXAgent].onStart { agent =>
    // Register MyApp to JMX registry when starting the application
    agent.register[MyApp](self)
  }

  private var accessCount: Long = 0

  @JMX(description = "application stats")
  def stats: MyAppStats = {
    MyAppStats(accessCount)
  }
}