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

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

copylibraryDependencies += Cinnamon.library.cinnamonCHMetricsJvmMetrics

Maven

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

Gradle

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

Metrics 3

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

sbt

copylibraryDependencies += Cinnamon.library.cinnamonCHMetrics3JvmMetrics

Maven

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

Gradle

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

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

copycinnamon.chmetrics {
  registrants += jvm-metrics
}

Reference

copycinnamon.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

copypackage 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

copypackage 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:

copycinnamon.chmetrics {
  registrants += sample-registrant

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

    some-setting = on
  }
}