環境設定

環境設定

気の利いたデフォルト値が提供されるので、環境設定を定義することなくAkkaを使用することができます。 後に、デフォルトの動作を変更したり、特定のランタイム環境に合わせて設定を修正しなければならない場合があります。 あなたが修正するかもしれない設定の典型的な例:

  • ログレベルとロガーのバックエンド

  • リモーティングを有効化

  • メッセージシリアライザ

  • ルータの定義

  • ディスパッチャのチューニング

Akkaは Typesafe Config Library を使用しており、これはAkkaの使用にかかわらず独自のアプリケーションやライブラリの環境設定にも適しています。 このライブラリは外部依存関係のないJavaで実装されていますので、 そのドキュメント(特に ConfigFactory)を見てください。 以下は要約になります。

警告

2.9.xのScala REPLからAkkaを使用していて、独自のClassLoaderをActorSystemに提供していない場合は、REPLで提供されているContext ClassLoaderの欠点を回避するためにREPLを "-Yrepl-sync" で開始します。

環境設定を読み込む場所

Akkaのすべての環境設定は ActorSystem のインスタンス内に保持され、別の言い方をすると外から見ると ActorSystem は環境設定情報の唯一のコンシューマです。アクターシステムを構築するときに、 Config オブジェクトを渡すか、 ConfigFactory.load() を渡しても同じです(適切なクラスローダーで)。 デフォルトでは、クラスパスのルートにある application.conf`application.jsonapplication.properties のすべてを解析します。詳しくはそれぞれのドキュメントを参照してください 。 アクターシステムは、クラスパスのルートにあるすべての reference.conf リソースをマージしてフォールバック環境設定を形成します。つまり、内部的に以下を使用します。

appConfig.withFallback(ConfigFactory.defaultReference(classLoader))

原理としては、このコードにデフォルト値は含まれていませんが、当該ライブラリで提供されている reference.conf に存在しています。

最も高い優先順位は、システムプロパティとして与えられたオーバーライドに与えられます。 HOCON仕様 (下部)を参照してください。 また、デフォルトで application になっているアプリケーションの環境設定は、 config.resource プロパティを使ってオーバーライドすることができます(詳細は、 Config docs 参照)。

注釈

Akkaアプリケーションを作成する場合は、クラスパスのルートにある application.conf に環境設定をしてください。 Akkaベースのライブラリを作成する場合は、jarファイルのルートにある reference.conf に環境設定をしてください。

JarJar、OneJar、アセンブリまたは任意のjar-bundlerを使用する場合

警告

Akkaの環境設定方法は、独自のreference.confファイルを持つすべてのモジュール/ jarの概念に大きく依存しており、これらのすべてが環境設定によって検出され、読み込まれます。 残念ながら、これは、複数のjarファイルを同じjarファイルに入れてマージすると、すべてのreference.confsもマージする必要があることを意味します。 そうしないと、すべてのデフォルト値が失われ、Akkaは機能しません。

Mavenを使用してアプリケーションをパッケージ化する場合、 Resource TransformersApache Maven Shade Plugin を使用して、ビルドクラスパス上のすべてのreference.confsを1つにマージします。

プラグインの環境設定は次のようになります:

<plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-shade-plugin</artifactId>
 <version>1.5</version>
 <executions>
  <execution>
   <phase>package</phase>
   <goals>
    <goal>shade</goal>
   </goals>
   <configuration>
    <shadedArtifactAttached>true</shadedArtifactAttached>
    <shadedClassifierName>allinone</shadedClassifierName>
    <artifactSet>
     <includes>
      <include>*:*</include>
     </includes>
    </artifactSet>
    <transformers>
      <transformer
       implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
       <resource>reference.conf</resource>
      </transformer>
      <transformer
       implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
       <manifestEntries>
        <Main-Class>akka.Main</Main-Class>
       </manifestEntries>
      </transformer>
    </transformers>
   </configuration>
  </execution>
 </executions>
</plugin>

カスタムのapplication.conf

カスタムの application.conf は次のようになります:

# In this file you can override any option defined in the reference files.
# Copy in parts of the reference files and modify as you please.

akka {

  # Loggers to register at boot time (akka.event.Logging$DefaultLogger logs
  # to STDOUT)
  loggers = ["akka.event.slf4j.Slf4jLogger"]

  # Log level used by the configured loggers (see "loggers") as soon
  # as they have been started; before that, see "stdout-loglevel"
  # Options: OFF, ERROR, WARNING, INFO, DEBUG
  loglevel = "DEBUG"

  # Log level for the very basic logger activated during ActorSystem startup.
  # This logger prints the log messages to stdout (System.out).
  # Options: OFF, ERROR, WARNING, INFO, DEBUG
  stdout-loglevel = "DEBUG"

  # Filter of log events that is used by the LoggingAdapter before
  # publishing log events to the eventStream.
  logging-filter = "akka.event.slf4j.Slf4jLoggingFilter"

  actor {
    provider = "cluster"

    default-dispatcher {
      # Throughput for default Dispatcher, set to 1 for as fair as possible
      throughput = 10
    }
  }

  remote {
    # The port clients should connect to. Default is 2552.
    netty.tcp.port = 4711
  }
}

ファイルのインクルード

場合によっては、別の環境設定ファイルをインクルードすると便利な場合もあります。たとえば、すべての環境に依存しない設定の application.conf がある場合、特定の環境設定をオーバーライドします。

-Dconfig.resource=/dev.conf でシステムプロパティを指定すると、 application.conf をインクルードしている dev.conf ファイルが読み込まれます。

dev.conf:

include "application"

akka {
  loglevel = "DEBUG"
}

より高度なインクルードと置換メカニズムについては、 HOCON で説明しています。

環境設定のログ出力

システムまたは設定プロパティーの akka.log-config-on-starton に設定されている場合、アクターシステムの起動時に完全な環境設定がINFOレベルでログに出力されます。 これは、使用されている環境設定が不明確な場合に便利です。

疑念がある場合は、環境設定オブジェクトを使用する前または使用した後で、設定オブジェクトを簡単かつうまく検査して、アクターシステムを構築することもできます。

Welcome to Scala version @scalaVersion@ (Java HotSpot(TM) 64-Bit Server VM, Java 1.8.0).
Type in expressions to have them evaluated.
Type :help for more information.

scala> import com.typesafe.config._
import com.typesafe.config._

scala> ConfigFactory.parseString("a.b=12")
res0: com.typesafe.config.Config = Config(SimpleConfigObject({"a" : {"b" : 12}}))

scala> res0.root.render
res1: java.lang.String =
{
    # String: 1
    "a" : {
        # String: 1
        "b" : 12
    }
}

すべての項目の前のコメントは、元々の設定(ファイルと行番号)と可能性のある設定のコメント(例: リファレンス環境設定)です。 リファレンスとマージされ、アクターシステムによって解析された設定は、次のように表示されます。

final ActorSystem system = ActorSystem.create();
System.out.println(system.settings());
// this is a shortcut for system.settings().config().root().render()

ClassLoadersについて

環境設定ファイルのいくつかの場所では、Akkaがインスタンス化するクラスの完全修飾クラス名を指定することができます。 これは、ClassLoader を使用して、Javaリフレクションで行われます。 アプリケーションコンテナやOSGiバンドルのような厳しい環境で適切なものを取得することは、必ずしも自明ではありませんが、Akkaの現在のアプローチは、それぞれの ActorSystem 実装が現在のスレッドのコンテキストクラスローダー(有効でなければ this.getClass.getClassLoader のような独自ローダのみ)を格納し、それをすべてのリフレクションアクセスに使用します。 これは、Akkaをブートクラスパスに置くと、奇妙な場所から NullPointerException が生成されることを意味します。これは単純にサポートされていません。

アプリケーション固有の設定

環境設定は、アプリケーション固有の設定にも使用できます。 以下で説明されているように、これらの設定を拡張機能に配置することをお勧めします。

複数のActorSystemの設定

複数の ActorSystem がある(またはライブラリを書いていて、アプリケーションのものとは別の ActorSystem が存在する)場合は、各システムの環境設定を分けたいかもしれません。

ConfigFactory.load() がクラスパス全体の名前と一致するすべてのリソースをマージしているとすれば、その機能を利用し、環境設定の階層内のアクターシステムを区別するのが最も簡単です:

myapp1 {
  akka.loglevel = "WARNING"
  my.own.setting = 43
}
myapp2 {
  akka.loglevel = "ERROR"
  app2.setting = "appname"
}
my.own.setting = 42
my.other.setting = "hello"
val config = ConfigFactory.load()
val app1 = ActorSystem("MyApp1", config.getConfig("myapp1").withFallback(config))
val app2 = ActorSystem("MyApp2",
  config.getConfig("myapp2").withOnlyPath("akka").withFallback(config))

これらの2つのサンプルは、「サブツリーの持ち上げ」トリックの異なるバリエーションを示しています。1つ目のケースでは、アクターシステム内からアクセス可能な環境設定は以下のとおりです。

akka.loglevel = "WARNING"
my.own.setting = 43
my.other.setting = "hello"
// plus myapp1 and myapp2 subtrees

2つ目は、「akka」サブツリーのみが持ち上げられ、以下の結果が得られます。

akka.loglevel = "ERROR"
my.own.setting = 42
my.other.setting = "hello"
// plus myapp1 and myapp2 subtrees

注釈

環境設定ライブラリは本当に強力で、すべての機能はここで説明する手頃な範囲を超えています。 特に、他のファイルに他の環境設定ファイルを含める方法( ファイルのインクルード の小さな例を参照)と、パスの置換によって環境設定ツリーの一部をコピーする方法がありますが説明しません。

ActorSystem をインスタンス化するときに、他の方法で環境設定をプログラムで解析することもできます。

import akka.actor.ActorSystem
import com.typesafe.config.ConfigFactory
    val customConf = ConfigFactory.parseString("""
      akka.actor.deployment {
        /my-service {
          router = round-robin-pool
          nr-of-instances = 3
        }
      }
      """)
    // ConfigFactory.load sandwiches customConfig between default reference
    // config and default overrides, and then resolves it.
    val system = ActorSystem("MySystem", ConfigFactory.load(customConf))

カスタムロケーションから環境設定を読み込む

application.conf をコードやシステムプロパティを使って置き換える、或いは補うことができます。

ConfigFactory.load() (デフォルトでAkkaが使用)を使用している場合、 -Dconfig.resource=whatever-Dconfig.file=whatever-Dconfig.url=whatever の何れかを定義することで application.conf を置き換えることができます。

-Dconfig.resource` 等で指定された置換ファイルの中から、まだ尚 application.{conf,json,properties} を使いたい場合は、 include "application" をすることができます。include "application" の前に指定された設定はインクルードされたファイルによって上書きされ、後のものはインクルードされたファイルを上書きします。

コードでは、多くのカスタマイズオプションがあります。

ConfigFactory.load() のいくつかのオーバーロードがあります。 これらは、システムプロパティ(オーバーライド)とデフォルト(reference.conf による)に挟まれるものを指定し、通常の application.{conf,json,properties} を置き換え、 -Dconfig.file 等を置き換えることができる。

ConfigFactory.load() のもっとも単純な変形はリソースのベースネーム(application の代わり)です。 application.{conf,json,properties} の代わりに myname.confmyname.jsonmyname.properties が使われます。

もっとも柔軟な変形は ConfigFactory のメソッドを使ってロードできる Config オブジェクトです。 例えば、 ConfigFactory.parseString() を使ってコードで文字列を設定するか、mapと ConfigFactory.parseMap() を作るか、ファイルを読み込むことができます。

以下のように、カスタム設定を通常の設定と組み合わせることもできます。

// make a Config with just your special setting
Config myConfig =
  ConfigFactory.parseString("something=somethingElse");
// load the normal config stack (system props,
// then application.conf, then reference.conf)
Config regularConfig =
  ConfigFactory.load();
// override regular stack with myConfig
Config combined =
  myConfig.withFallback(regularConfig);
// put the result in between the overrides
// (system props) and defaults again
Config complete =
  ConfigFactory.load(combined);
// create ActorSystem
ActorSystem system =
  ActorSystem.create("myname", complete);

Config オブジェクトを扱うとき、ケーキには3つの「層」があることに留意してください:

  • ConfigFactory.defaultOverrides() (システムプロパティ)

  • アプリの設定

  • ConfigFactory.defaultReference() (reference.conf)

通常の目標は、他の2つだけを残して中間層をカスタマイズすることです。

  • ConfigFactory.load() はスタック全体を読み込む

  • ConfigFactory.load() のオーバーロードにより、異なる中間層を指定

  • ConfigFactory.parse() の変動は単一のファイルやリソースを読み込む

2つの層をスタックするには、 override.withFallback(fallback) を使います。システムプロパティ(defaultOverrides()) を一番上に、 reference.conf (defaultReference())を一番下にしてください。

コードを記述するのではなく、 application.conf に別の include 文を追加することができます。 application.conf の先頭のインクルードは application.conf の残りの部分によって上書きされ、後のものは前のものより優先されます。

アクターデプロイメントの環境設定

特定のアクターのデプロイ設定は、環境設定の akka.actor.deployment セクションで定義することができます。 デプロイセクションでは、ディスパッチャ、メールボックス、ルーター設定、リモートデプロイなどを定義することができます。 これらの機能の環境設定については、対応するトピックを詳しい説明の章で説明しています。 例は次のようになります。

akka.actor.deployment {

  # '/user/actorA/actorB' is a remote deployed actor
  /actorA/actorB {
    remote = "akka.tcp://sampleActorSystem@127.0.0.1:2553"
  }
  
  # all direct children of '/user/actorC' have a dedicated dispatcher 
  "/actorC/*" {
    dispatcher = my-dispatcher
  }

  # all descendants of '/user/actorC' (direct children, and their children recursively)
  # have a dedicated dispatcher
  "/actorC/**" {
    dispatcher = my-dispatcher
  }
  
  # '/user/actorD/actorE' has a special priority mailbox
  /actorD/actorE {
    mailbox = prio-mailbox
  }
  
  # '/user/actorF/actorG/actorH' is a random pool
  /actorF/actorG/actorH {
    router = random-pool
    nr-of-instances = 5
  }
}

my-dispatcher {
  fork-join-executor.parallelism-min = 10
  fork-join-executor.parallelism-max = 10
}
prio-mailbox {
  mailbox-type = "a.b.MyPrioMailbox"
}

注釈

特定アクターのデプロイセクションは、 /user を基準にしたアクタのパスで識別されます。

アスタリスクをアクターパスセクションのワイルドカードとして使用することができるので、 /*/sampleActor と階層のそのレベルのすべての sampleActor にマッチさせることができます。 さらに、次の点に注意してください。

  • 末尾にワイルドカードを使用して、あるレベルのすべてのアクターにマッチさせることもできます: /someParent/*

  • 末尾にダブルワイルドカードを使用して、すべての子アクターとその子を再帰的にマッチさせることができます: /someParent/**

  • 非ワイルドカードマッチは常にワイルドカードより優先順位が高く、ワイルドカードマッチはダブルワイルドカードより優先度が高いので、 /foo/bar/foo/** より特定のもの とみなされる /foo/* より特定のもの とみなされます。 最も高い優先順位の一致のみが使用されます。

  • ワイルドカード**は /foo*/bar/f*o/bar などのように部分的にセクションにマッチさせることは できません

注釈

ダブルワイルドカードは末尾にのみ置くことができます。

リファレンス環境設定の一覧

各Akkaモジュールには、デフォルト値を持つリファレンス環境設定ファイルがあります。

akka-actor

akka-agent

akka-camel

akka-cluster

akka-multi-node-testkit

akka-persistence

akka-remote

akka-remote (artery)

akka-testkit

akka-cluster-metrics ~~~~~~~~~~~~--------

akka-cluster-tools ~~~~~~~~~~~~------

akka-cluster-sharding ~~~~~~~~~~~~---------

akka-distributed-data ~~~~~~~~~~~~---------

Contents