環境設定
気の利いたデフォルト値が提供されるので、環境設定を定義することなく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.json
、 application.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 Transformers の Apache 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-start
が on
に設定されている場合、アクターシステムの起動時に完全な環境設定が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
が生成されることを意味します。これは単純にサポートされていません。
アプリケーション固有の設定
環境設定は、アプリケーション固有の設定にも使用できます。 以下で説明されているように、これらの設定を拡張機能に配置することをお勧めします。
- Scala API: Application specific settings
- Java API: Application specific settings
複数の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.conf
、 myname.json
、 myname.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