scalaconsultants / mesmer-akka-agent

Akka extension and agent exposing application telemetry and events via OpenTelemetry interface

Version Matrix
CI Release Snapshot
Scala CI Release Artifacts Snapshot Artifacts

Mesmer Akka Agent

Mesmer Akka Agent is an OpenTelemetry instrumentation library for Akka applications.

Compatibility

Mesmer has been tested with:

  • Scala: 2.13.x
  • Akka Actors: 2.6.8, 2.6.9, 2.6.10, 2.6.11, 2.6.12, 2.6.13, 2.6.14
  • Akka HTTP: 10.1.8, 10.2.0, 10.2.1, 10.2.2, 10.2.3, 10.2.4
  • JVM: 1.8+

Getting started

Mesmer consists of two parts:

  • Akka extension - that runs in the background and is responsible for exporting the metrics to your chosen backend
  • JVM agent - that instruments Akka classes to expose metrics for the extension

Both parts need to be included in the application for Mesmer to work.

Akka extension:

Add the following dependency to your build.sbt file:

libraryDependencies += "io.scalac" %% "mesmer-akka-extension" % "<version>"

Add this entry to your application.conf:

akka.actor.typed.extensions= ["io.scalac.mesmer.extension.Mesmer"] 

JVM agent:

Download the latest agent jar from https://github.com/ScalaConsultants/mesmer-akka-agent/releases and add a parameter when running your JVM:

java -javaagent {PATH_TO_JAR}/mesmer-akka-agent.jar

where PATH_TO_JAR is your absolute path to the Mesmer agent jar.

Exporters:

As mesmer uses OpenTelemetry underneath to export data to metric backend you need to set up an exporter. All exporters require OpenTelemetry SDK present, so make sure you have one added to your project - without this all measurement operations will be NoOp. You can check out how to configure Prometheus with Akka HTTP here.

Supported metrics

Mesmer currently supports the following Akka modules:

  • Akka (core)
  • Akka Cluster
  • Akka Persistence
  • Akka Streams

For a detailed list of metrics go to metrics

Architecture

See overview.

//TODO

Local testing

example subproject contains a test application that uses Akka Cluster sharding with Mesmer Akka Agent extension. Go here for more information.