Registrants

Cinnamon for Coda Hale Metrics supports some additional metrics out-of-the-box. See the instructions below for enabling the additional metrics.

Dependencies

The additional metrics are only available for the Coda Hale metrics plugin, so make sure that your build is set up according to the instructions for the reporters.

JVM metrics

Note

The JVM metrics reporter is deprecated and is being replaced by JVM Metrics Producer.

This module provides some general JVM metrics. You must add it as a dependency and enable it in configuration.

Add the JVM metrics dependency to your build:

sbt

libraryDependencies += Cinnamon.library.cinnamonCHMetricsJvmMetrics

Maven

<dependency>
    <groupId>com.lightbend.cinnamon</groupId>
    <artifactId>cinnamon-chmetrics-jvm-metrics</artifactId>
    <version>2.20.3</version>
</dependency>

Gradle

dependencies {
  implementation group: 'com.lightbend.cinnamon', name: 'cinnamon-chmetrics-jvm-metrics', version: '2.20.3'
}

Metrics 3

If you’re using the Coda Hale Metrics 3 module, use the chmetrics3 version of JVM metrics:

sbt

libraryDependencies += Cinnamon.library.cinnamonCHMetrics3JvmMetrics

Maven

<dependency>
    <groupId>com.lightbend.cinnamon</groupId>
    <artifactId>cinnamon-chmetrics3-jvm-metrics</artifactId>
    <version>2.20.3</version>
</dependency>

Gradle

dependencies {
  implementation group: 'com.lightbend.cinnamon', name: 'cinnamon-chmetrics3-jvm-metrics', version: '2.20.3'
}

Configuration

Below is the configuration to enable the JVM metrics. The Reference tab shows all the configurable settings for the JVM metrics—you can turn the different sections on or off individually.

Required

cinnamon.chmetrics {
  registrants += jvm-metrics
}

Reference

cinnamon.chmetrics {
  jvm-metrics {

    memory-usage {
      # Enable memory usage metrics
      metrics = on
      # The category name for all memory usage metrics
      category = "memory-usage"
    }

    garbage-collection {
      # Enable garbage collection metrics
      metrics = on
      # The category name for all garbage collection metrics
      category = "garbage-collection"
    }

    class-loading {
      # Enable class loading metrics
      metrics = on
      # The category name for all class loading metrics
      category = "class-loading"
    }
  }
}

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.

Memory Usage

All memory sizes are in bytes, and all metrics start with metrics.jvm.memory-usage.

JVM heap memory

heap.init The initial amount of heap memory requested by the JVM
heap.used The amount of heap memory used by the JVM
heap.max The maximum amount of heap memory that the JVM can use
heap.committed The amount of heap memory that the JVM is guaranteed
heap.usage The ratio between heap.max and heap.used

JVM non-heap memory

non-heap.init The initial amount of non-heap memory requested by the JVM
non-heap.used The amount of non-heap memory used by the JVM
non-heap.max The maximum amount of non-heap memory that the JVM can use
non-heap.committed The amount of non-heap memory that the JVM is guaranteed
non-heap.usage The ratio between non-heap.max and non-heap.used

JVM total memory

total.init The sum of heap.init and non-heap.init
total.used The sum of heap.used and non-heap.used
total.max The sum of heap.max and non-heap.max
total.committed The sum of heap.committed and non-heap.committed
total.usage The ratio between total.max and total.used

Per memory pool

The following information is also presented per memory pool, e.g. PS-Eden-Space.

pools.<pool name>.usage The ratio between the maximum size and used size of the memory pool

Garbage Collection

All metrics start with metrics.jvm.garbage-collection and information is per collector phase, e.g. PS-MarkSweep.

<phase name>.count The number of times that the phase has been run
<phase name>.time The accumulated elapsed time of all runs of the collection phase in milliseconds

Class Loading

All metrics star with metrics.jvm.class-loading.

loaded The number of loaded classes
unloaded The number of unloaded classes

Custom registrants

Custom registrants can be implemented to add Metric Sets directly to the Coda Hale Metrics registry.

To create a custom registrant, implement the Registrant interface. A Config parameter is optional, and will provide access to the configuration section enabled below. Create an Array of MetricSets in the start method, which will be added to the Coda Hale Metrics registry when the backends are started.

Scala

package sample.registrant

import com.codahale.metrics.MetricSet
import com.lightbend.cinnamon.chmetrics.registrant.Registrant
import com.typesafe.config.Config

class SampleRegistrant(config: Config) extends Registrant {
  // use optional Config parameter to access settings
  val someSetting = config.getBoolean("some-setting")

  override def start(): Array[MetricSet] = {
    Array(new SomeMetricSet(someSetting))
  }

  override def stop(): Unit = {
    // clean up any resources here
  }
}

Java

package sample.registrant;

import com.codahale.metrics.MetricSet;
import com.lightbend.cinnamon.chmetrics.registrant.Registrant;
import com.typesafe.config.Config;

public class SampleRegistrant implements Registrant {
  private final boolean someSetting;

  public SampleRegistrant(Config config) {
    // use optional Config parameter to access settings
    this.someSetting = config.getBoolean("some-setting");
  }

  @Override
  public MetricSet[] start() {
    return new MetricSet[] {new SomeMetricSet(someSetting)};
  }

  @Override
  public void stop() {
    // clean up any resources here
  }

}

Enable the custom registrant in configuration:

cinnamon.chmetrics {
  registrants += sample-registrant

  sample-registrant {
    registrant-class = "sample.registrant.SampleRegistrant"

    some-setting = on
  }
}