New to Akka? Start with the Akka SDK.

Akka Cluster Sharding

Akka Insights is capable of capturing additional data for Akka Cluster Sharding. These metrics are collected via the built-in Akka Cluster Sharding telemetry SPI, providing visibility into shard region buffer usage, shard home resolution latency, message drops, and shard handoff operations.

Note

For shard region delivered messages, shards per region, and entities per shard metrics, see the Akka Cluster metrics section.

Cinnamon Akka Cluster Sharding module dependency

After adding the Cinnamon Agent as described in the setup, make sure that you add the Cinnamon Akka Cluster Sharding module dependency to your build file:

sbt

// Use Akka Cluster Sharding instrumentation
libraryDependencies += Cinnamon.library.cinnamonAkkaClusterSharding

Maven

<!-- Use Akka Cluster Sharding instrumentation -->
<dependency>
  <groupId>com.lightbend.cinnamon</groupId>
  <artifactId>cinnamon-akka-cluster-sharding_2.13</artifactId>
  <version>2.22.1</version>
</dependency>

Gradle

// Use Akka Cluster Sharding instrumentation
dependencies {
    implementation group: 'com.lightbend.cinnamon', name: 'cinnamon-akka-cluster-sharding_2.13', version: '2.22.1'
}

Cluster Sharding metrics

The following Cluster Sharding metrics are recorded, type of metric in parenthesis. All metrics are recorded per shard region entity type name. These metrics are enabled automatically when the module dependency is added — no additional configuration is required.

Note

All time-related metrics use nanoseconds unless specified otherwise.

Shard Region metrics:

Shard region buffer size (gauge) — the current number of messages buffered in the shard region while waiting for shard homes to be resolved by the coordinator.
Shard region message dropped (counter) — number of messages dropped when the shard region buffer is full.
Shard home latency (recorder) — the time from when the shard region requests a shard home from the coordinator until the shard home is received. This measures the latency of shard allocation and can indicate coordinator responsiveness issues.
Shard handoff latency (recorder) — the time from when a shard handoff is initiated until the handoff completes. This measures the duration of shard rebalancing operations between nodes.