Configuration¶
Specifying the configuration file¶
If you don’t specify a configuration file then Akka uses default values, corresponding to the akka-reference.conf that you see below. You can specify your own configuration file to override any property in the reference config. You only have to define the properties that differ from the default configuration.
The location of the config file to use can be specified in various ways:
- Define the -Dakka.config=... system property parameter with a file path to configuration file.
- Put an akka.conf file in the root of the classpath.
- Define the AKKA_HOME environment variable pointing to the root of the Akka distribution. The config is taken from the AKKA_HOME/config/akka.conf. You can also point to the AKKA_HOME by specifying the -Dakka.home=... system property parameter.
If several of these ways to specify the config file are used at the same time the precedence is the order as given above, i.e. you can always redefine the location with the -Dakka.config=... system property.
Defining the configuration file¶
Here is the reference configuration file:
####################
# Akka Config File #
####################
# This file has all the default settings, so all these could be removed with no visible effect.
# Modify as needed.
akka {
version = "1.2" # Akka version, checked against the runtime version of Akka.
enabled-modules = [] # Comma separated list of the enabled modules. Options: ["remote", "camel", "http"]
time-unit = "seconds" # Time unit for all timeout properties throughout the config
event-handlers = ["akka.event.EventHandler$DefaultListener"] # event handlers to register at boot time (EventHandler$DefaultListener logs to STDOUT)
event-handler-level = "INFO" # Options: ERROR, WARNING, INFO, DEBUG
# These boot classes are loaded (and created) automatically when the Akka Microkernel boots up
# Can be used to bootstrap your application(s)
# Should be the FQN (Fully Qualified Name) of the boot class which needs to have a default constructor
# boot = ["sample.camel.Boot",
# "sample.rest.java.Boot",
# "sample.rest.scala.Boot",
# "sample.security.Boot"]
boot = []
actor {
timeout = 5 # Default timeout for Future based invocations
# - Actor: ? and ask
# - UntypedActor: ask
# - TypedActor: methods with non-void return type
serialize-messages = off # Does a deep clone of (non-primitive) messages to ensure immutability
throughput = 5 # Default throughput for all ExecutorBasedEventDrivenDispatcher, set to 1 for complete fairness
throughput-deadline-time = -1 # Default throughput deadline for all ExecutorBasedEventDrivenDispatcher, set to 0 or negative for no deadline
dispatcher-shutdown-timeout = 1 # Using the akka.time-unit, how long dispatchers by default will wait for new actors until they shut down
default-dispatcher {
type = "GlobalExecutorBasedEventDriven" # Must be one of the following, all "Global*" are non-configurable
# - ExecutorBasedEventDriven
# - ExecutorBasedEventDrivenWorkStealing
# - GlobalExecutorBasedEventDriven
keep-alive-time = 60 # Keep alive time for threads
core-pool-size-factor = 1.0 # No of core threads ... ceil(available processors * factor)
max-pool-size-factor = 4.0 # Max no of threads ... ceil(available processors * factor)
executor-bounds = -1 # Makes the Executor bounded, -1 is unbounded
task-queue-size = -1 # Specifies the bounded capacity of the task queue (< 1 == unbounded)
task-queue-type = "linked" # Specifies which type of task queue will be used, can be "array" or "linked" (default)
allow-core-timeout = on # Allow core threads to time out
rejection-policy = "caller-runs" # abort, caller-runs, discard-oldest, discard
throughput = 5 # Throughput for ExecutorBasedEventDrivenDispatcher, set to 1 for complete fairness
throughput-deadline-time = -1 # Throughput deadline for ExecutorBasedEventDrivenDispatcher, set to 0 or negative for no deadline
mailbox-capacity = -1 # If negative (or zero) then an unbounded mailbox is used (default)
# If positive then a bounded mailbox is used and the capacity is set using the property
# NOTE: setting a mailbox to 'blocking' can be a bit dangerous,
# could lead to deadlock, use with care
#
# The following are only used for ExecutorBasedEventDriven
# and only if mailbox-capacity > 0
mailbox-push-timeout-time = 10 # Specifies the timeout to add a new message to a mailbox that is full - negative number means infinite timeout
# (in unit defined by the time-unit property)
}
debug {
receive = "false" # enable function of Actor.loggable(), which is
# to log any received message at DEBUG level
autoreceive = "false" # enable DEBUG logging of all AutoReceiveMessages
# (Kill, PoisonPill and the like)
lifecycle = "false" # enable DEBUG logging of actor lifecycle changes
}
}
stm {
fair = on # Should global transactions be fair or non-fair (non fair yield better performance)
max-retries = 1000
timeout = 5 # Default timeout for blocking transactions and transaction set (in unit defined by
# the time-unit property)
write-skew = true
blocking-allowed = false
interruptible = false
speculative = true
quick-release = true
propagation = "requires"
trace-level = "none"
}
http {
hostname = "localhost"
port = 9998
#If you are using akka.http.AkkaRestServlet
filters = ["akka.security.AkkaSecurityFilterFactory"] # List with all jersey filters to use
# resource-packages = ["sample.rest.scala",
# "sample.rest.java",
# "sample.security"] # List with all resource packages for your Jersey services
resource-packages = []
# The authentication service to use. Need to be overridden (sample now)
# authenticator = "sample.security.BasicAuthenticationService"
authenticator = "N/A"
# Uncomment if you are using the KerberosAuthenticationActor
# kerberos {
# servicePrincipal = "HTTP/[email protected]"
# keyTabLocation = "URL to keytab"
# kerberosDebug = "true"
# realm = "EXAMPLE.COM"
# }
kerberos {
servicePrincipal = "N/A"
keyTabLocation = "N/A"
kerberosDebug = "N/A"
realm = ""
}
#If you are using akka.http.AkkaMistServlet
mist-dispatcher {
#type = "GlobalExecutorBasedEventDriven" # Uncomment if you want to use a different dispatcher than the default one for Comet
}
connection-close = true # toggles the addition of the "Connection" response header with a "close" value
root-actor-id = "_httproot" # the id of the actor to use as the root endpoint
root-actor-builtin = true # toggles the use of the built-in root endpoint base class
timeout = 1000 # the default timeout for all async requests (in ms)
expired-header-name = "Async-Timeout" # the name of the response header to use when an async request expires
expired-header-value = "expired" # the value of the response header to use when an async request expires
}
remote {
# secure-cookie = "050E0A0D0D06010A00000900040D060F0C09060B" # generate your own with '$AKKA_HOME/scripts/generate_config_with_secure_cookie.sh' or using 'Crypt.generateSecureCookie'
secure-cookie = ""
compression-scheme = "" # Options: "zlib" (lzf to come), leave out for no compression
zlib-compression-level = 6 # Options: 0-9 (1 being fastest and 9 being the most compressed), default is 6
layer = "akka.remote.netty.NettyRemoteSupport"
server {
hostname = "localhost" # The hostname or IP that clients should connect to
port = 2552 # The port clients should connect to. Default is 2552 (AKKA)
message-frame-size = 1048576 # Increase this if you want to be able to send messages with large payloads
connection-timeout = 100 # Number in time-unit
require-cookie = off # Should the remote server require that it peers share the same secure-cookie (defined in the 'remote' section)?
untrusted-mode = off # Enable untrusted mode for full security of server managed actors, allows untrusted clients to connect.
backlog = 4096 # Sets the size of the connection backlog
execution-pool-keepalive = 60# Length in akka.time-unit how long core threads will be kept alive if idling
execution-pool-size = 16# Size of the core pool of the remote execution unit
max-channel-memory-size = 0 # Maximum channel size, 0 for off
max-total-memory-size = 0 # Maximum total size of all channels, 0 for off
}
client {
buffering {
retry-message-send-on-failure = off # Buffer outbound messages when send failed, if off you'll get an exception instead
capacity = -1 # If negative (or zero) then an unbounded mailbox is used (default)
# If positive then a bounded mailbox is used and the capacity is set using the property
}
reconnect-delay = 5 # Number in time-unit
read-timeout = 10 # Number in time-unit
message-frame-size = 1048576 # Size in bytes
reap-futures-delay = 5 # Number in time-unit
reconnection-time-window = 600 # Maximum time window that a client should try to reconnect for
}
}
test {
timefactor = "1.0" # factor by which to scale timeouts during tests, e.g. to account for shared build system load
}
}
A custom akka.conf might look like this:
# In this file you can override any option defined in the 'akka-reference.conf' file.
# Copy in all or parts of the 'akka-reference.conf' file and modify as you please.
akka {
event-handlers = ["akka.event.slf4j.Slf4jEventHandler"]
# Comma separated list of the enabled modules.
enabled-modules = ["camel", "remote"]
# These boot classes are loaded (and created) automatically when the Akka Microkernel boots up
# Can be used to bootstrap your application(s)
# Should be the FQN (Fully Qualified Name) of the boot class which needs to have a default constructor
boot = ["sample.camel.Boot",
"sample.myservice.Boot"]
actor {
throughput = 10 # Throughput for ExecutorBasedEventDrivenDispatcher, set to 1 for complete fairness
}
remote {
server {
port = 2562 # The port clients should connect to. Default is 2552 (AKKA)
}
}
}
Specifying files for different modes¶
You can use different configuration files for different purposes by specifying a mode option, either as -Dakka.mode=... system property or as AKKA_MODE=... environment variable. For example using DEBUG log level when in development mode. Run with -Dakka.mode=dev and place the following akka.dev.conf in the root of the classpath.
akka.dev.conf:
akka {
event-handler-level = "DEBUG"
}
The mode option works in the same way when using configuration files in AKKA_HOME/config/ directory.
The mode option is not used when specifying the configuration file with -Dakka.config=... system property.
Including files¶
Sometimes it can be useful to include another configuration file, for example if you have one akka.conf with all environment independent settings and then override some settings for specific modes.
akka.dev.conf:
include "akka.conf"
akka {
event-handler-level = "DEBUG"
}
Showing Configuration Source¶
If the system property akka.output.config.source is set to anything but null, then the source from which Akka reads its configuration is printed to the console during application startup.
Summary of System Properties¶
- akka.home (AKKA_HOME): where Akka searches for configuration
- akka.config: explicit configuration file location
- akka.mode (AKKA_MODE): modify configuration file name for multiple profiles
- akka.output.config.source: whether to print configuration source to console