These tutorials target Micronaut Framework 3. Read, Guides for Micronaut Framework 4.

Table of Contents

Collect Metrics with Micronaut

Learn how to collect standard and custom metrics with the Micronaut framework.

Authors: Burt Beckwith

Micronaut Version: 3.9.2

1. Getting Started

In this guide, we will create a Micronaut application written in Kotlin.

We’ll use Micronaut Micrometer to expose application metric data with Micrometer.

2. What you will need

To complete this guide, you will need the following:

  • Some time on your hands

  • A decent text editor or IDE

  • JDK 1.8 or greater installed with JAVA_HOME configured appropriately

3. Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

4. Writing the Application

Create an application using the Micronaut Command Line Interface or with Micronaut Launch.

mn create-app example.micronaut.micronautguide \
    --features=micrometer-annotation,data-jdbc,flyway,graalvm \
    --build=gradle
    --lang=kotlin
If you don’t specify the --build argument, Gradle is used as the build tool.
If you don’t specify the --lang argument, Java is used as the language.

The previous command creates a Micronaut application with the default package example.micronaut in a directory named micronautguide.

If you use Micronaut Launch, select Micronaut Application as application type and add micrometer-annotation, data-jdbc, flyway, and graalvm features.

If you have an existing Micronaut application and want to add the functionality described here, you can view the dependency and configuration changes from the specified features and apply those changes to your application.

Setup IntelliJ IDEA to develop Micronaut Applications.

4.1. Metrics Configuration

Several groups of metrics are enabled by default; these include system metrics (JVM info, uptime, etc.), as well as metrics tracking web requests, DataSource activity, and others. Overall metrics can be enabled or disabled, and groups can be individually enabled or disabled in configuration.

Add the following to application.yml:

src/main/resources/application.yml
micronaut:
  metrics:
    enabled: true (1)
    binders: (2)
      files:
        enabled: true
      jdbc:
        enabled: true
      jvm:
        enabled: true
      logback:
        enabled: true
      processor:
        enabled: true
      uptime:
        enabled: true
      web:
        enabled: true
1 Change to false to disable all metrics, e.g., per-environment
2 These default to true and are only here for convenience, to be able to disable a subset of metrics

4.2. Custom Metrics

If the built-in metrics aren’t enough, you can easily add custom metrics with the following annotations.

@Timed

Creates a Timer metric that contains the total time, max time and count.

@Counted

Creates a Counter metric that only contains a count.

If you want to create your own gauge, you can inject io.micrometer.core.instrument.MeterRegistry to your bean.

4.3. Data Source Metrics

DataSource metrics are enabled by default if you use the HikariCP (the default), Tomcat JDBC, or Commons DBCP connection pool.

4.4. Database Migration with Flyway

We need a way to create the database schema. For that, we use Micronaut integration with Flyway.

Flyway automates schema changes, significantly simplifying schema management tasks, such as migrating, rolling back, and reproducing in multiple environments.

Add the following snippet to include the necessary dependencies:

build.gradle
implementation("io.micronaut.flyway:micronaut-flyway")
runtimeOnly("org.flywaydb:flyway-mysql")

We will enable Flyway in application.yml and configure it to perform migrations on one of the defined data sources.

src/main/resources/application.yml
flyway:
  datasources:
    default:
      enabled: true (1)
1 Enable Flyway for the default datasource.
Configuring multiple data sources is as simple as enabling Flyway for each one. You can also specify directories that will be used for migrating each data source. Review the Micronaut Flyway documentation for additional details.

Flyway migration will be automatically triggered before your Micronaut application starts. Flyway will read migration commands in the resources/db/migration/ directory, execute them if necessary, and verify that the configured data source is consistent with them.

Create the following migration files with the database schema creation:

src/main/resources/db/migration/V1__schema.sql
DROP TABLE IF EXISTS book;

CREATE TABLE book (
    id    BIGINT GENERATED BY DEFAULT AS IDENTITY,
    name  VARCHAR(255) NOT NULL,
    isbn  VARCHAR(255) NOT NULL UNIQUE
);

During application startup, Flyway will execute the SQL file and create the schema needed for the application.

4.5. Domain

Create a Book domain class that uses Micronaut Data JDBC:

src/main/kotlin/example/micronaut/Book.kt
package example.micronaut

import io.micronaut.data.annotation.GeneratedValue
import io.micronaut.data.annotation.GeneratedValue.Type.AUTO
import io.micronaut.data.annotation.Id
import io.micronaut.data.annotation.MappedEntity

@MappedEntity (1)
class Book(var isbn: String, var name: String) {
    @Id (2)
    @GeneratedValue(AUTO) (3)
    var id: Long? = null
}
1 Annotate the class with @MappedEntity to map the class to the table defined in the schema.
2 Specifies the ID of an entity
3 Specifies that the property value is generated by the database and not included in inserts

4.6. BookRepository

Next, create the BookRepository interface to define database operations. Micronaut Data will implement the interface at compilation time:

src/main/kotlin/example/micronaut/BookRepository.kt
package example.micronaut

import io.micronaut.data.jdbc.annotation.JdbcRepository
import io.micronaut.data.model.query.builder.sql.Dialect.H2
import io.micronaut.data.repository.CrudRepository
import java.util.Optional
import javax.validation.constraints.NotBlank

@JdbcRepository(dialect = H2) (1)
interface BookRepository : CrudRepository<Book, Long> { (2)

    fun findByIsbn(isbn: @NotBlank String): Optional<Book>
}
1 @JdbcRepository with a specific dialect.
2 Specifies that Book is the root entity, and the primary key type is Long.

4.7. Data populator class

Create a DataPopulator class to create some example database entries when the application starts:

src/main/kotlin/example/micronaut/DataPopulator.kt
package example.micronaut

import io.micronaut.context.annotation.Requires
import io.micronaut.context.env.Environment.TEST
import io.micronaut.context.event.StartupEvent
import io.micronaut.runtime.event.annotation.EventListener
import jakarta.inject.Singleton
import javax.transaction.Transactional

@Singleton (1)
open class DataPopulator(private val bookRepository: BookRepository) { (2)

    @EventListener (3)
    @Transactional (4)
    open fun init(event: StartupEvent) {
        if (bookRepository.count() == 0L) {
            bookRepository.save(Book("1491950358", "Building Microservices"))
            bookRepository.save(Book("1680502395", "Release It!"))
            bookRepository.save(Book("0321601912", "Continuous Delivery"))
        }
    }
}
1 Use jakarta.inject.Singleton to designate a class as a singleton.
2 Use constructor injection to inject a bean of type BookRepository.
3 Annotate a method with @EventListener to subscribe to an event you define as the method parameter.
4 You can declare a method or class as transactional with the javax.transaction.Transactional annotation.

4.8. BookController

Create BookController to access Book instances (and trigger JDBC metric data):

src/main/kotlin/example/micronaut/BookController.kt
package example.micronaut

import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.scheduling.TaskExecutors
import io.micronaut.scheduling.annotation.ExecuteOn
import io.micrometer.core.annotation.Timed
import io.micrometer.core.annotation.Counted

import java.util.Optional

@Controller("/books") (1)
@ExecuteOn(TaskExecutors.IO) (2)
open class BookController(private val bookRepository: BookRepository) { (3)

    @Get(4)
    @Timed("books.index") (5)
    open fun index(): Iterable<Book> = bookRepository.findAll()

    @Get("/{isbn}") (6)
    @Counted("books.find") (7)
    open fun findBook(isbn: String): Optional<Book> = bookRepository.findByIsbn(isbn)
}
1 The class is defined as a controller with the @Controller annotation mapped to the path /books.
2 It is critical that any blocking I/O operations (such as fetching the data from the database) are offloaded to a separate thread pool that does not block the Event loop.
3 Use constructor injection to inject a bean of type BookRepository.
4 Maps a GET request to /books, which returns a list of Book
5 Creates a Timer metric with the given name. If the name is omitted, defaults to method.timed.
6 Maps a GET request to /books/{isbn}, which attempts to show a Book. This illustrates the use of a URL path variable.
7 Creates a Counter metric with the given name. If the name is omitted, defaults to the method.counted.

4.9. Custom Metrics

To see custom metrics in action, create a service that periodically retrieves the current Bitcoin price in USD using REST.

4.9.1. Model

We’ll need a data class to represent the REST response. Create the BitcoinPrice class:

src/main/kotlin/example/micronaut/crypto/BitcoinPrice.kt
package example.micronaut.crypto

import io.micronaut.core.annotation.Introspected

@Introspected (1)
class BitcoinPrice(private val data: Data) {

    val price: Float
        get() = data.price

    @Introspected (1)
    class Data(val price: Float)
}
1 Annotate the class with @Introspected to generate BeanIntrospection metadata at compilation time. This information can be used, for example, to render the POJO as JSON using Jackson without using reflection.

4.9.2. Kucoin Declarative HTTP Client

Create declarative Micronaut HTTP Client interface that will be implemented at compile time:

src/main/kotlin/example/micronaut/crypto/PriceClient.kt
package example.micronaut.crypto

import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.QueryValue
import io.micronaut.http.client.annotation.Client

@Client(id = "kucoin") (1)
abstract class PriceClient {

    @Get("/api/v1/market/orderbook/level1")
    abstract fun latest(@QueryValue symbol: String): BitcoinPrice

    fun latestInUSD(): BitcoinPrice = latest("BTC-USDT")
}
1 Use @Client to use declarative HTTP Clients. You can annotate interfaces or abstract classes. You can use the id member to provide a service identifier or specify the URL directly as the annotation’s value.

4.9.3. HTTP Service Configuration

Modify application.yml to configure the URL for the kucoin Service ID:

src/main/resources/application.yml
micronaut:
  http:
    services:
      kucoin: (1)
        urls:
          - "https://api.kucoin.com" (2)
1 The ID we used with @Client
2 The URL for the kucoin service

4.9.4. Service

Create a CryptoService class that uses PriceClient and updates three custom meters:

src/main/kotlin/example/micronaut/crypto/CryptoService.kt
package example.micronaut.crypto

import io.micrometer.core.instrument.Counter
import io.micrometer.core.instrument.MeterRegistry
import io.micrometer.core.instrument.Timer
import io.micronaut.scheduling.annotation.Scheduled
import jakarta.inject.Singleton
import org.slf4j.LoggerFactory
import java.util.concurrent.atomic.AtomicInteger

@Singleton (1)
class CryptoService constructor(
    private val priceClient: PriceClient, (2)
    meterRegistry: MeterRegistry) {

    private val log = LoggerFactory.getLogger(javaClass.name)

    private val checks: Counter
    private val time: Timer
    private val latestPriceUsd = AtomicInteger(0)

    init {
        checks = meterRegistry.counter("bitcoin.price.checks") (3)
        time = meterRegistry.timer("bitcoin.price.time") (4)
        meterRegistry.gauge("bitcoin.price.latest", latestPriceUsd) (5)
    }

    @Scheduled(fixedRate = "\${crypto.updateFrequency:1h}",
            initialDelay = "\${crypto.initialDelay:0s}") (6)
    fun updatePrice() {
        time.recordCallable { (7)
            try {
                checks.increment() (8)
                latestPriceUsd.set(priceClient.latestInUSD().price.toInt()) (9)
            } catch (e: Exception) {
                log.error("Problem checking price", e)
            }
        }
    }
}
1 Use jakarta.inject.Singleton to designate a class as a singleton.
2 Use constructor injection to inject PriceClient, MeterRegistry, and ObjectMapper beans
3 Create a Counter to track the total number of updates
4 Create a Timer to track the total time performing updates
5 Create a Gauge to track the most recent update
6 Use the Scheduled annotation to configure regular updates
7 Update the Timer
8 Increment the Counter
9 Update the Gauge with the latest price

5. Testing the Application

Create the src/test/resources/application-test.yml configuration file for tests.

src/test/resources/application-test.yml
crypto:
  initialDelay: 10h (1)
1 Disable crypto price lookups with a long initial delay

Create a test class to verify metrics functionality:

src/test/kotlin/example/micronaut/MetricsTest.kt
package example.micronaut

import io.micrometer.core.instrument.MeterRegistry
import io.micrometer.core.instrument.Tags
import io.micronaut.core.type.Argument
import io.micronaut.http.HttpRequest
import io.micronaut.http.client.HttpClient
import io.micronaut.http.client.annotation.Client
import io.micronaut.logging.LogLevel.ALL
import io.micronaut.logging.LoggingSystem
import io.micronaut.test.extensions.junit5.annotation.MicronautTest
import jakarta.inject.Inject
import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.Assertions.assertFalse
import org.junit.jupiter.api.Assertions.assertTrue
import org.junit.jupiter.api.Test
import org.slf4j.LoggerFactory
import java.util.concurrent.TimeUnit

@MicronautTest (1)
class MetricsTest(@Client("/") val httpClient: HttpClient) { (4)

    @Inject
    lateinit var meterRegistry: MeterRegistry (2)

    @Inject
    lateinit var loggingSystem: LoggingSystem (3)

    @Test
    fun testExpectedMeters() {

        val names = meterRegistry.meters.map { it.id.name }

        // check that a subset of expected meters exist
        assertTrue(names.contains("jvm.memory.max"))
        assertTrue(names.contains("process.uptime"))
        assertTrue(names.contains("system.cpu.usage"))
        assertTrue(names.contains("process.files.open"))
        assertTrue(names.contains("logback.events"))
        assertTrue(names.contains("hikaricp.connections.max"))

        // these will be lazily created
        assertFalse(names.contains("http.client.requests"))
        assertFalse(names.contains("http.server.requests"))
    }

    @Test
    fun testHttp() {

        val timer = meterRegistry.timer(
            "http.server.requests", Tags.of(
                "exception", "none",
                "method", "GET",
                "status", "200",
                "uri", "/books"))

        assertEquals(0, timer.count())

        val bookIndexTimer = meterRegistry.timer("books.index",
            Tags.of("exception", "none"))

        assertEquals(0, bookIndexTimer.count())

        httpClient.toBlocking().retrieve(
            HttpRequest.GET<Any>("/books"),
            Argument.listOf(Book::class.java))

        assertEquals(1, timer.count())
        assertEquals(1, bookIndexTimer.count())
        assertTrue(0.0 < bookIndexTimer.totalTime(TimeUnit.MILLISECONDS))
        assertTrue(0.0 < bookIndexTimer.max(TimeUnit.MILLISECONDS))

        val bookFindCounter = meterRegistry.counter("books.find",
            Tags.of("result", "success",
                "exception", "none"))

        assertEquals(0.0, bookFindCounter.count())

        httpClient.toBlocking().retrieve(
            HttpRequest.GET<Any>("/books/1491950358"),
            Argument.of(Book::class.java)
        )

        assertEquals(1.0, bookFindCounter.count())
    }

    @Test
    fun testLogback() {

        val counter = meterRegistry.counter("logback.events", Tags.of("level", "info"))
        val initial = counter.count()

        val logger = LoggerFactory.getLogger("testing.testing")
        loggingSystem.setLogLevel("testing.testing", ALL)

        logger.trace("trace")
        logger.debug("debug")
        logger.info("info")
        logger.warn("warn")
        logger.error("error")

        assertEquals(initial + 1, counter.count(), 0.000001)
    }

    @Test
    fun testMetricsEndpoint() {

        val response = httpClient.toBlocking().retrieve(
            HttpRequest.GET<Any>("/metrics"),
            Argument.mapOf(String::class.java, Any::class.java)
        )

        assertTrue(response.containsKey("names"))
        assertTrue(response["names"] is List<*>)

        val names = response["names"] as List<String>

        // check that a subset of expected meters exist
        assertTrue(names.contains("jvm.memory.max"))
        assertTrue(names.contains("process.uptime"))
        assertTrue(names.contains("system.cpu.usage"))
        assertTrue(names.contains("process.files.open"))
        assertTrue(names.contains("logback.events"))
        assertTrue(names.contains("hikaricp.connections.max"))
    }

    @Test
    fun testOneMetricEndpoint() {

        val response = httpClient.toBlocking().retrieve(
            HttpRequest.GET<Any>("/metrics/jvm.memory.used"),
            Argument.mapOf(String::class.java, Any::class.java))

        val name = response["name"] as String
        assertEquals("jvm.memory.used", name)

        val measurements = response["measurements"] as List<Map<String, Any>>
        assertEquals(1, measurements.size)

        val value = measurements[0]["value"] as Double
        assertTrue(value > 0)
    }
}
1 Annotate the class with @MicronautTest so the Micronaut framework will initialize the application context and the embedded server. More info.
2 Inject the MeterRegistry bean
3 Inject the LoggingSystem bean
4 Inject the HttpClient bean and point it to the embedded server.

Create an additional test class to verify the custom metrics:

src/test/kotlin/example/micronaut/CryptoUpdatesTest.kt
package example.micronaut

import example.micronaut.crypto.CryptoService
import io.micrometer.core.instrument.MeterRegistry
import io.micronaut.context.ApplicationContext
import io.micronaut.context.annotation.Requires
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.QueryValue
import io.micronaut.runtime.server.EmbeddedServer
import org.junit.jupiter.api.AfterAll
import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.Assertions.assertTrue
import org.junit.jupiter.api.BeforeAll
import org.junit.jupiter.api.Test
import org.junit.jupiter.api.TestInstance
import org.junit.jupiter.api.TestInstance.Lifecycle.PER_CLASS
import java.util.concurrent.TimeUnit.MILLISECONDS

@TestInstance(PER_CLASS)
class CryptoUpdatesTest {

    lateinit var embeddedServer: EmbeddedServer

    lateinit var kucoinEmbeddedServer: EmbeddedServer

    @BeforeAll
    fun beforeAll() {

        kucoinEmbeddedServer = ApplicationContext.run(EmbeddedServer::class.java,
                mapOf("spec.name" to "MetricsTestKucoin"))

        embeddedServer = ApplicationContext.run(EmbeddedServer::class.java,
                mapOf("micronaut.http.services.kucoin.url" to "http://localhost:" + kucoinEmbeddedServer.getPort()))
    }

    @AfterAll
    fun afterAll() {
        embeddedServer.close()
        kucoinEmbeddedServer.close()
    }

    @Test
    fun testCryptoUpdates() {
        val cryptoService = embeddedServer.applicationContext.getBean(CryptoService::class.java)
        val meterRegistry = embeddedServer.applicationContext.getBean(MeterRegistry::class.java)
        val counter = meterRegistry.counter("bitcoin.price.checks")
        val timer = meterRegistry.timer("bitcoin.price.time")

        assertEquals(0.0, counter.count(), 0.000001)
        assertEquals(0.0, timer.totalTime(MILLISECONDS))

        val checks = 3

        for (i in 0 until checks) {
            cryptoService.updatePrice()
        }

        assertEquals(checks.toDouble(), counter.count(), 0.000001)
        assertTrue(timer.totalTime(MILLISECONDS) > 0)
    }

    @Requires(property = "spec.name", value = "MetricsTestKucoin")
    @Controller
    class MockKucoinController {

        private val RESPONSE = """
{
   "code":"200000",
   "data":{
      "time":1654865889872,
      "sequence":"1630823934334",
      "price":"29670.4",
      "size":"0.00008436",
      "bestBid":"29666.4",
      "bestBidSize":"0.16848947",
      "bestAsk":"29666.5",
      "bestAskSize":"2.37840044"
   }
}
"""

        @Get("/api/v1/market/orderbook/level1")
        fun latest(@QueryValue symbol: String?) = RESPONSE
    }
}

The previous test creates two Micronaut embedded servers. One mocks the kucoin API, the other is our application. The test uses @Requires to conditionally load a controller only for the kucoin bean context. We used an identifier with @Client, which makes it easy to point our HTTP client to the mock server.

5.1. Running the tests

To run the tests:

./gradlew test

Then open build/reports/tests/test/index.html in a browser to see the results.

6. Running the Application

To run the application, use the ./gradlew run command, which starts the application on port 8080.

Alternately, to make the Bitcoin price update occur more frequently to see the effects on metrics, start the application with a config override to update every five seconds:

./gradlew run --args="-crypto.updateFrequency=5s"

You can retrieve a list of known metrics using cURL:

curl localhost:8080/metrics

The response should look like this:

{
  "names": [
    "bitcoin.price.checks",
    "bitcoin.price.latest",
    "bitcoin.price.time",
    "executor",
    "executor.active",
    "executor.completed",
    "executor.pool.core",
    "executor.pool.max",
    "executor.pool.size",
    "executor.queue.remaining",
    "executor.queued",
    "hikaricp.connections",
    "hikaricp.connections.acquire",
    "hikaricp.connections.active",
    ...
    "jvm.threads.peak",
    "jvm.threads.states",
    "logback.events",
    "process.cpu.usage",
    "process.files.max",
    "process.files.open",
    "process.start.time",
    "process.uptime",
    "system.cpu.count",
    "system.cpu.usage",
    "system.load.average.1m"
  ]
}

After the application has been running for a bit and has made a few Bitcoin price checks, we can view the related metric values:

curl localhost:8080/metrics/bitcoin.price.latest
{
  "measurements": [{ "statistic": "VALUE", "value": 29659.0 } ],
  "name": "bitcoin.price.latest"
}
curl localhost:8080/metrics/bitcoin.price.checks
{
  "measurements": [{ "statistic": "COUNT", "value": 5.0 } ],
  "name": "bitcoin.price.checks"
}
curl localhost:8080/metrics/bitcoin.price.time
{
  "baseUnit": "seconds",
  "measurements": [
    { "statistic": "COUNT",      "value": 5.0 },
    { "statistic": "TOTAL_TIME", "value": 2.525546791 },
    { "statistic": "MAX",        "value": 0.851958216 }
  ],
  "name": "bitcoin.price.time"
}

7. Generate a Micronaut Application Native Executable with GraalVM

We will use GraalVM, the polyglot embeddable virtual machine, to generate a native executable of our Micronaut application.

Compiling native executables ahead of time with GraalVM improves startup time and reduces the memory footprint of JVM-based applications.

Only Java and Kotlin projects support using GraalVM’s native-image tool. Groovy relies heavily on reflection, which is only partially supported by GraalVM.

7.1. Native executable generation

The easiest way to install GraalVM on Linux or Mac is to use SDKMan.io.

Java 11
sdk install java 22.3.r11-grl
If you still use Java 8, use the JDK11 version of GraalVM.
Java 17
sdk install java 22.3.r17-grl

For installation on Windows, or for manual installation on Linux or Mac, see the GraalVM Getting Started documentation.

After installing GraalVM, install the native-image component, which is not installed by default:

gu install native-image

To generate a native executable using Gradle, run:

./gradlew nativeCompile

The native executable is created in build/native/nativeCompile directory and can be run with build/native/nativeCompile/micronautguide.

It is possible to customize the name of the native executable or pass additional parameters to GraalVM:

build.gradle
graalvmNative {
    binaries {
        main {
            imageName.set('mn-graalvm-application') (1)
            buildArgs.add('--verbose') (2)
        }
    }
}
1 The native executable name will now be mn-graalvm-application
2 It is possible to pass extra arguments to build the native executable

Start the native image and run the cURL commands above to see that the application works the same way as before, with faster startup and response times.

8. Next steps

In combination with the /metrics endpoint, you often want to register a specific type of reporter. See the Micronaut Micrometer documentation to learn about the supported libraries for reporting metrics.