Changing an actor system's configuration

An actor system is the basis of YDB. Each component of the system is represented by one or more actors.
Each actor is allocated to a specific ExecutorPool corresponding to the actor's task.
Changing the configuration lets you more accurately distribute the number of cores reserved for each type of task.

Actor system config description

The actor system configuration contains an enumeration of ExecutorPools, their mapping to task types, and the actor system scheduler configurations.

The following task types and their respective pools are currently supported:

  • System: Designed to perform fast internal YDB operations.
  • User: Includes the entire user load for handling and executing incoming requests.
  • Batch: Tasks that have no strict limit on the execution time, mainly running background operations.
  • IO: Responsible for performing any tasks with blocking operations (for example, writing logs to a file).
  • IC: Interconnect, includes all the load associated with communication between nodes.

Each pool is described by the Executor field as shown in the example below.

Executor {
  Type: BASIC
  Threads: 9
  SpinThreshold: 1
  Name: "System"
}

A summary of the main fields:

  • Type: Currently, two types are supported, such as BASIC and IO. All pools, except IO, are of the BASIC type.
  • Threads: The number of threads (concurrently running actors) in this pool.
  • SpinThreshold: The number of CPU cycles before going to sleep if there are no tasks, which a thread running as an actor will take (affects the CPU usage and request latency under low loads).
  • Name: The pool name to be displayed for the node in Monitoring.

Mapping pools to task types is done by setting the pool sequence number in special fields. Pool numbering starts from 0. Multiple task types can be set for a single pool.

List of fields with their respective tasks:

  • SysExecutor: System
  • UserExecutor: User
  • BatchExecutor: Batch
  • IoExecutor: IO

Example:

SysExecutor: 0
UserExecutor: 1
BatchExecutor: 2
IoExecutor: 3

The IC pool is set in a different way, via ServiceExecutor, as shown in the example below.

ServiceExecutor {
  ServiceName: "Interconnect"
  ExecutorId: 4
}

The actor system scheduler is responsible for the delivery of deferred messages exchanged by actors and is set with the following parameters:

  • Resolution: The minimum time offset step in microseconds.
  • SpinThreshold: Similar to the pool parameter, the number of CPU cycles before going to sleep if there are no messages.
  • ProgressThreshold: The maximum time offset step in microseconds.

If, for an unknown reason, the scheduler thread is stuck, it will send messages according to the lagging time, offsetting it by the ProgressThreshold value each time.

We do not recommend changing the scheduler config. You should only change the number of threads in the pool configs.

Example of the default actor system configuration:

Executor {
  Type: BASIC
  Threads: 9
  SpinThreshold: 1
  Name: "System"
}
Executor {
  Type: BASIC
  Threads: 16
  SpinThreshold: 1
  Name: "User"
}
Executor {
  Type: BASIC
  Threads: 7
  SpinThreshold: 1
  Name: "Batch"
}
Executor {
  Type: IO
  Threads: 1
  Name: "IO"
}
Executor {
  Type: BASIC
  Threads: 3
  SpinThreshold: 10
  Name: "IC"
  TimePerMailboxMicroSecs: 100
}
SysExecutor: 0
UserExecutor: 1
IoExecutor: 3
BatchExecutor: 2
ServiceExecutor {
  ServiceName: "Interconnect"
  ExecutorId: 4
}

On static nodes

Static nodes take the configuration of the actor system from the /opt/ydb/cfg/config.yaml file.

After changing the configuration, restart the node.

On dynamic nodes

Dynamic nodes take the configuration from the CMS. To change it, you can use the following command:

ConfigureRequest {
  Actions {
    AddConfigItem {
      ConfigItem {
        // UsageScope: { ... }
        Config {
          ActorSystemConfig {
            <actor system config>
          }  
        }
        MergeStrategy: 3
      }
    }
  }
}

```bash
ydbd -s <endpoint> admin console execute --domain=<domain> --retry=10 actorsystem.txt