Skip to main content

Actors in Java: Configuring Local Actor Systems

Posted by jcmansigian on October 30, 2013 at 4:58 PM PDT


Configuration of an actor system affects the way in which the Akka actor libraries and microkernel interact with actors. The visibility of a configuration is limited to the specific actor system with which the configuration has been associated. The effective configuration for any given actor system is a merger of three sources. In Fig. 1 below the precedence of overriding values flows from the top of the stack ( highest precedence ) to the bottom.

Fig. 1 Configuration Stack

Source Description
system properties Java system properties.
application.conf File contains application specific overrides to the file reference.conf below.
reference.conf File contains the entire set of Akka actor default configuration values.

Why Would You Want To Configure

Although the Akka actor libraries and microkernel can work to an extent without intentional configuration by relying on values from reference.conf here are some of the reasons why in practice you will want to configure your actor application.

  • You need interoperation between more than one actor system.
  • You need to use remote hosts to run your actor systems.
  • You need to create actors from a remote console.
  • For compatibility with a remote host you need to change the transport protocol from the default to something else.
  • You need to multicast messages to groups of actors and would like to use one of the routers that comes with the Akka actor distribution instead of writing your own router.
  • Your application requires that more than one actor share the same queue of messages ( share same mailbox ).
  • For crash recovery you want to implement durable mailboxes. Durable mailboxes are actor mailboxes that are backed up by a persistent store. Saved messages flow again when the system restarts.
  • You are tasked with implementing a highly reliable and performant failover enabled cluster of servers to meet stringent processing demands.
  • As a way of defining the characteristics of software transactional memory ( STM ) that is operating in your transaction based application.
  • You want to protect your actor system from external attack.
  • You are in development and need debugging information.
  • Company auditors and/or security require logging of operations to be done in a prescribed way.

Scope of This Exercise

Configuration of an actor system is a vast subject. Configurations that will be covered here are limited to useful common configuration patterns that have local scope. Configuring for remote operations is the subject of a future post. We will be learning to manipulate application.conf, the application specific source for configuration information. The global reference.conf file will be left without modification; always preferring to override default values at the application level.

What You Will Need

  • Akka actor distribution 2.2.1. See attached AkkaHelp.html file for download and deployment directions.
  • A local Java actor application to apply the configuration to. For instance you can use the source for the “Fortune Cookie Application” attached below and also available at the learning actors in java site. Or else you can write your own local actor application.

Where Does The Configuration File Go

In this exercise we will be putting the application configuration file application.conf in a directory that is at the base of the classpath for the local actor application being worked. Other places are possible but this default is the simplest and usually serves very well.
Here is a directory listing of a sample application with configuration file.


Now we will look at various configuration options. The following sections will each present a configuration pattern.

Loglevel Options

The loglevel setting shows basic operational information at various levels of detail. See comment for options. Experiment with different settings to see the difference.

   # INFO, WARNING, ERROR OFF levels also can be substituted here.
   loglevel = "DEBUG"

It is also possible to completely turn off logging using this configuration setting.

     stdout-loglevel = "OFF"
     loglevel = "OFF"

Log Dead Letters

Dead letters are actor messages that for one reason or another have not found their way to the recipient actor. If you find that you are losing messages in your application you can elect to turn on the logging of dead letters. Then you can create a dedicated diagnosis actor that subscribes to the Event Stream to receive all dead letters so you can analyze the problem.

    log-dead-letters = on
    log-dead-letters-during-shutdown = on
    # max number of dead letters logged
    log-dead-letters = 250

Show Entire Configuration

This setting will reveal the entire set of merged configuration values that are operative for the configured actor system. This is a very long log listing that appears when the configured actor system starts up. Never used for production code but can be useful sometimes in development to check assumptions about how the actor system is configured.

    log-config-on-start = on

Debug Life Cycle

An important part of debugging is stepping through logic and watching the transformations that occur and comparing them to expectations. With actors it is possible to set up life cycle debug logging that exposes all transitions that an actor makes during its lifetime.

lifecycle = on

Going Forward

Continuing posts in the "Actors in Java" series will appear on the 10th, 20th and 30th( earlier if necessary ) of each month. The next post will be "Actors in Java: Configuring Remote Actor Systems".

FortuneCookieApplication.zip2.01 KB
AkkaHelp.html2.64 KB