Reporters

Cinnamon supports several Coda Hale Metrics reporters out-of-the-box. See the instructions below for enabling the Coda Hale Metrics plugin and configuring reporters.

Cinnamon dependency

First make sure that your build is configured to use the Cinnamon Agent.

Add the Coda Hale Metrics plugin dependency to your build:

sbt

copylibraryDependencies += Cinnamon.library.cinnamonCHMetrics

Maven

copy<dependency>
  <groupId>com.lightbend.cinnamon</groupId>
  <artifactId>cinnamon-chmetrics</artifactId>
  <version>2.21.2</version>
</dependency>

Gradle

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

Metrics 3

Cinnamon supports both Coda Hale Metrics version 4 and version 3. Metrics 4 is used by default by the Cinnamon Coda Hale Metrics core module above. Cinnamon can also use Metrics 3, which may be needed to align with other dependencies. The Cinnamon Coda Hale Metrics reporters are compatible across both Metrics 3 and 4, and mark the core module dependency as provided so that either version can be selected. To select Metrics 3, use the Coda Hale Metrics 3 module in place of the default:

sbt

copylibraryDependencies += Cinnamon.library.cinnamonCHMetrics3

Maven

copy<dependency>
    <groupId>com.lightbend.cinnamon</groupId>
    <artifactId>cinnamon-chmetrics3</artifactId>
    <version>2.21.2</version>
</dependency>

Gradle

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

JMX reporter

You need the Cinnamon dependency for Coda Hale Metrics.

Below is the configuration needed to set up Coda Hale Metrics to use the provided JMX reporter. The Reference tab shows all the configurable settings for the JMX reporter.

Required

copycinnamon.chmetrics {
  reporters += "jmx-reporter"
}

Reference

copycinnamon.chmetrics {
  jmx-reporter {

    # Time unit to convert rates to
    convert-rates-to = "SECONDS"

    # Time unit to convert durations to
    convert-durations-to = "MILLISECONDS"
  }
}

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.

JMX properties

For more information on configuring JMX properties, see the JMX documentation for Java.

To include properties in an sbt-native-packager distribution, you can use bash script defines or bat script defines.

Console reporter

You need the Cinnamon dependency for Coda Hale Metrics.

Below is the configuration needed to set up Coda Hale Metrics to use the provided Console reporter. The Reference tab shows all the configurable settings for the Console reporter.

Required

copycinnamon.chmetrics {
  reporters += "console-reporter"
}

Reference

copycinnamon.chmetrics {
  console-reporter {

    # Time unit to convert rates to
    convert-rates-to = "SECONDS"

    # Time unit to convert durations to
    convert-durations-to = "MILLISECONDS"

    # Format numbers for this locale
    formatted-for = "en"

    # Frequency with which to report metrics
    frequency = 5s
  }
}

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.

SLF4J reporter

You need the Cinnamon dependency for Coda Hale Metrics.

Below is the configuration needed to set up Coda Hale Metrics to use the provided SLF4J reporter. The Reference tab shows all the configurable settings for the SLF4J reporter.

Required

copycinnamon.chmetrics {
  reporters += "slf4j-reporter"
}

Reference

copycinnamon.chmetrics {
  slf4j-reporter {

    # Time unit to convert rates to
    convert-rates-to = "SECONDS"

    # Time unit to convert durations to
    convert-durations-to = "MILLISECONDS"

    # Logger name to output to
    output-to = "output-sink"

    # Frequency with which to report metrics
    frequency = 5s
  }
}

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.

NOP reporter

You need the Cinnamon dependency for Coda Hale Metrics.

The NOP (No Operation) is a reporter that does nothing. It can be used to prevent Cinnamon from logging an error during start up about missing reporter(s). This can be useful if other means of getting metrics out of Cinnamon is used, e.g. via instrumentation of Coda Hale metrics.

Required

copycinnamon.chmetrics {
  reporters += "nop-reporter"
}

HTTP reporter

The HTTP reporter requires an extra dependency. First add the core Coda Hale Metrics dependency and the HTTP reporter dependency to your build:

sbt

copylibraryDependencies += Cinnamon.library.cinnamonCHMetrics
libraryDependencies += Cinnamon.library.cinnamonCHMetricsHttpReporter

Maven

copy<dependency>
    <groupId>com.lightbend.cinnamon</groupId>
    <artifactId>cinnamon-chmetrics</artifactId>
    <version>2.21.2</version>
</dependency>
<dependency>
  <groupId>com.lightbend.cinnamon</groupId>
  <artifactId>cinnamon-chmetrics-http-reporter_2.13</artifactId>
  <version>2.21.2</version>
</dependency>

Gradle

copydependencies {
  implementation group: 'com.lightbend.cinnamon', name: 'cinnamon-chmetrics', version: '2.21.2'
}
dependencies {
  implementation group: 'com.lightbend.cinnamon', name: 'cinnamon-chmetrics-http-reporter_2.13', version: '2.21.2'
}

Below is the configuration needed to set up Coda Hale Metrics to use the provided HTTP reporter. The Reference tab shows all the configurable settings for the HTTP reporter.

Required

copycinnamon.chmetrics {
  reporters += "http-reporter"
}

Example

copycinnamon.chmetrics {
  reporters += "http-reporter"

  http-reporter {
    host = "127.0.0.1"
    port = 8888
  }
}

Reference

copycinnamon.chmetrics {
  http-reporter {

    # Time unit to convert rates to
    convert-rates-to = "SECONDS"

    # Time unit to convert durations to
    convert-durations-to = "MILLISECONDS"

    # Frequency with which to report metrics
    frequency = 5s

    # Interface accept connections on
    host = "127.0.0.1"

    # Port to accept connections on
    port = 8080

    # Configuration of the actor system used by the http reporter
    reporter-actor-system {
      akka.instrumentations = []
      akka.stream.instrumentations = []
      akka.http.instrumentations = []
    }
  }
}

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 reporter-actor-system is the configuration used when starting a required ActorSystem for the HTTP reporter. With this configuration you can fine tune the configuration of this ActorSystem based on your underlying hardware. Please note that this reporter should not require a lot of resources so using the default settings may be overkill.

Multiple reporters

It is also possible to set up multiple reporters, provided or custom, to report to several places. Below is an example of how to use the JMX and Console reporters simultaneously:

copycinnamon.chmetrics {
  reporters += "console-reporter"
  reporters += "jmx-reporter"
}