CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-typesafe-akka--akka-cluster-sharding-2-13

Akka Cluster Sharding provides location transparency and automatic distribution of stateful actors across cluster nodes

Overview
Eval results
Files

configuration.mddocs/

Configuration and Settings

ClusterShardingSettings provides comprehensive configuration for tuning sharding behavior, performance, and operational characteristics. It supports both programmatic configuration and configuration file-based setup.

Creating Settings

From Actor System

Use default configuration from akka.cluster.sharding:

object ClusterShardingSettings {
  def apply(system: ActorSystem): ClusterShardingSettings
}

Usage Example:

val settings = ClusterShardingSettings(system)

From Config

Create settings from a custom configuration:

def apply(config: Config): ClusterShardingSettings

Usage Example:

val config = system.settings.config.getConfig("my-sharding")
val settings = ClusterShardingSettings(config)

Core Configuration Properties

Basic Settings

class ClusterShardingSettings(
  role: Option[String],
  rememberEntities: Boolean,
  journalPluginId: String,
  snapshotPluginId: String,
  stateStoreMode: String,
  rememberEntitiesStore: String,
  passivationStrategy: PassivationStrategy,
  shardFailureBackoff: FiniteDuration,
  entityRestartBackoff: FiniteDuration,
  rebalanceInterval: FiniteDuration,
  snapshotAfter: Int,
  keepNrOfBatches: Int,
  leastShardAllocationRebalanceThreshold: Int,
  leastShardAllocationMaxSimultaneousRebalance: Int,
  waitingForStateTimeout: FiniteDuration,
  updatingStateTimeout: FiniteDuration,
  coordinatorSingletonSettings: ClusterSingletonManagerSettings,
  coordinatorSingletonRole: Option[String],
  usePassivateIdleEntities: Boolean,
  tuningParameters: TuningParameters,
  coordinatorStateWriteMajorityPlus: Int,
  coordinatorStateReadMajorityPlus: Int,
  leastShardAllocationAbsoluteLimit: Int,
  leastShardAllocationRelativeLimit: Double
)

State Store Modes

object ClusterShardingSettings {
  val StateStoreModePersistence = "persistence"
  val StateStoreModeDData = "ddata"
}
  • StateStoreModePersistence: Use Akka Persistence for state storage (deprecated)
  • StateStoreModeDData: Use Akka Distributed Data for state storage (recommended)

Remember Entities Store Types

private[akka] val RememberEntitiesStoreDData = "ddata"
private[akka] val RememberEntitiesStoreEventsourced = "eventsourced"
private[akka] val RememberEntitiesStoreCustom = "custom"

Tuning Parameters

Core Tuning Parameters Class

class TuningParameters(
  coordinatorFailureBackoff: FiniteDuration,
  retryInterval: FiniteDuration,
  bufferSize: Int,
  handOffTimeout: FiniteDuration,
  shardStartTimeout: FiniteDuration,
  shardFailureBackoff: FiniteDuration,
  entityRestartBackoff: FiniteDuration,
  rebalanceInterval: FiniteDuration,
  snapshotAfter: Int,
  keepNrOfBatches: Int,
  leastShardAllocationRebalanceThreshold: Int,
  leastShardAllocationMaxSimultaneousRebalance: Int,
  waitingForStateTimeout: FiniteDuration,
  updatingStateTimeout: FiniteDuration,
  entityRecoveryStrategy: String,
  entityRecoveryConstantRateStrategyFrequency: FiniteDuration,
  entityRecoveryConstantRateStrategyNumberOfEntities: Int,
  coordinatorStateWriteMajorityPlus: Int,
  coordinatorStateReadMajorityPlus: Int,
  leastShardAllocationAbsoluteLimit: Int,
  leastShardAllocationRelativeLimit: Double,
  passivationStopTimeout: FiniteDuration
)

Key Tuning Parameters

  • coordinatorFailureBackoff: Backoff when coordinator fails (default: 5s)
  • retryInterval: Interval for retrying failed operations (default: 2s)
  • bufferSize: Message buffer size for pending operations (default: 1000)
  • handOffTimeout: Timeout for shard handoff during rebalancing (default: 10s)
  • shardStartTimeout: Timeout for starting new shards (default: 10s)
  • rebalanceInterval: Interval between rebalancing attempts (default: 10s)
  • snapshotAfter: Number of changes before taking snapshot (default: 1000)

Passivation Strategy Settings

Passivation Strategy Configuration

class PassivationStrategySettings(
  strategy: PassivationStrategy,
  idleEntitySettings: Option[IdleSettings],
  oldestEntitySettings: Option[OldestSettings],
  mostRecentlyUsedEntitySettings: Option[MostRecentlyUsedSettings],
  leastRecentlyUsedEntitySettings: Option[LeastRecentlyUsedSettings],
  leastFrequentlyUsedEntitySettings: Option[LeastFrequentlyUsedSettings]
)

Idle-based Passivation

class IdleSettings(
  timeout: FiniteDuration,
  interval: FiniteDuration
)

Configuration Example:

akka.cluster.sharding {
  passivation {
    strategy = idle
    idle-entity {
      timeout = 2m
      interval = 1m
    }
  }
}

Age-based Passivation Strategies

class OldestSettings(
  segmentSize: Int,
  proportionToPassivatePerRebalance: Double,
  idleTimeBeforeCleanUp: FiniteDuration
)

class LeastRecentlyUsedSettings(
  segmentSize: Int,
  proportionToPassivatePerRebalance: Double,
  idleTimeBeforeCleanUp: FiniteDuration
)

class MostRecentlyUsedSettings(
  segmentSize: Int,
  proportionToPassivatePerRebalance: Double,
  idleTimeBeforeCleanUp: FiniteDuration
)

class LeastFrequentlyUsedSettings(
  segmentSize: Int,
  proportionToPassivatePerRebalance: Double,
  idleTimeBeforeCleanUp: FiniteDuration
)

Settings Builder Methods

Role Configuration

def withRole(role: String): ClusterShardingSettings
def withRole(role: Option[String]): ClusterShardingSettings

Usage Example:

val settings = ClusterShardingSettings(system)
  .withRole("worker")

Remember Entities Configuration

def withRememberEntities(rememberEntities: Boolean): ClusterShardingSettings

State Store Configuration

def withStateStoreMode(mode: String): ClusterShardingSettings

Passivation Configuration

def withPassivationStrategy(strategy: PassivationStrategy): ClusterShardingSettings

Configuration File Example

Complete configuration example in application.conf:

akka.cluster.sharding {
  # Number of shard regions that must be available for the coordinator
  # to continue processing commands
  waiting-for-state-timeout = 5s
  
  # Timeout for updating distributed state (write/read)
  updating-state-timeout = 5s
  
  # The shard region for a entity type can be started on nodes filtered by role
  role = "worker"
  
  # When 'remember-entities' is enabled the Shard will automatically restart
  # entities that were previously running in the shard
  remember-entities = off
  
  # Set this to a time duration to have sharding passivate entities when they have not
  # received any message in this length of time
  passivation {
    strategy = idle
    idle-entity {
      timeout = 2m
      interval = 1m
    }
  }
  
  # Rebalancing is performed periodically based on this interval
  rebalance-interval = 10s
  
  # Absolute limit of how many shards the rebalance algorithm will rebalance
  # in one rebalance round
  least-shard-allocation-strategy.rebalance-absolute-limit = 20
  
  # Relative limit of how many shards the rebalance algorithm will rebalance
  # in one rebalance round.
  least-shard-allocation-strategy.rebalance-relative-limit = 0.1
  
  # The coordinator saves persistent snapshots after this number of changes
  snapshot-after = 1000
  
  # Setting for the default shard allocation strategy
  tuning {
    coordinator-failure-backoff = 5s
    retry-interval = 2s
    buffer-size = 1000
    handoff-timeout = 10s
    shard-start-timeout = 10s
    shard-failure-backoff = 10s
    entity-restart-backoff = 10s
    rebalance-interval = 10s
    snapshot-after = 1000
    keep-nr-of-batches = 2
  }
  
  # Settings for the coordinator singleton
  coordinator-singleton = ${akka.cluster.singleton}
  
  # Settings for remember entities store when using ddata
  distributed-data {
    # minCap parameter to MajorityWrite and MajorityRead consistency level
    majority-min-cap = 5
    durable.keys = ["shard-*"]
    
    # When using many entities with "remember entities" the Gossip message
    # can become to large if including to many in same message. Limit to 10 entries.
    max-delta-elements = 10
  }
}

Advanced Configuration

Coordinator Singleton Settings

coordinatorSingletonSettings: ClusterSingletonManagerSettings
coordinatorSingletonRole: Option[String]

Entity Recovery Strategy

Control how entities are recovered when remember-entities is enabled:

  • "all": Recover all entities immediately (default)
  • "constant": Recover entities at a constant rate

Lease Integration

useLeaseForRebalancing: Boolean
leaseSettings: Option[LeaseUsageSettings]

Settings Validation

The settings are validated on creation:

  • Timeouts must be positive
  • Buffer sizes must be positive
  • Percentages must be between 0.0 and 1.0
  • Required fields must be present

Install with Tessl CLI

npx tessl i tessl/maven-com-typesafe-akka--akka-cluster-sharding-2-13

docs

allocation-strategies.md

configuration.md

core-extension.md

external-allocation.md

index.md

message-routing.md

monitoring.md

tile.json