Asakusa on MapReduce リファレンス

この文書では、Asakusa on MapReduceが提供するGradle PluginやDSLコンパイラの設定、およびバッチアプリケーション実行時の設定などについて説明します。

Asakusa on MapReduce Gradle Plugin リファレンス

Asakusa on MapReduce Gradle Pluginが提供する機能とインターフェースについて個々に解説します。

プラグイン

asakusafw-mapreduce

アプリケーションプロジェクトで、Asakusa on MapReduceのさまざまな機能を有効にする [1] 。

このプラグインは asakusafw-sdk プラグインや asakusafw-organizer プラグインを拡張するように作られているため、それぞれのプラグインも併せて有効にする必要がある（ apply plugin: 'asakusafw-mapreduce' だけではほとんどの機能を利用できません）。

[1]	com.asakusafw.mapreduce.gradle.plugins.AsakusafwMapReducePlugin

タスク

mapreduceCompileBatchapps

Asakusa DSL Compiler for MapReduceを利用してDSLをコンパイルする [2] 。

asakusafw-sdk プラグインが有効である場合にのみ利用可能。

attachComponentMapReduce

デプロイメントアーカイブにMapReduce向けのバッチアプリケーションを実行するためのコンポーネントを追加する。

asakusafw-organizer プラグインが有効である場合にのみ利用可能。

asakusafwOrganizer.mapreduce.enabled に true が指定されている場合、自動的に有効になる。

attachMapReduceBatchapps

デプロイメントアーカイブに mapreduceCompileBatchapps でコンパイルした結果を含める。

asakusafw-sdk , asakusafw-organizer の両プラグインがいずれも有効である場合にのみ利用可能。

asakusafwOrganizer.batchapps.enabled に true が指定されている場合、自動的に有効になる。

[2]	com.asakusafw.gradle.tasks.AsakusaCompileTask

タスク拡張

assemble

デプロイメントアーカイブを生成する。

asakusafw-mapreduce と asakusafw-organizer プラグインがいずれも有効である場合、 mapreduceCompileBatchapps が依存関係に追加される。

compileBatchapp

Asakusa DSLコンパイラを使ってバッチアプリケーションのコンパイルを行い、実行可能モジュールを生成する。

asakusafw-mapreduce プラグインが有効である場合、 mapreduceCompileBatchapps が依存関係に追加される。

jarBatchapp

compileBatchapp タスクで生成したバッチアプリケーションを含むjarファイルを生成する。

asakusafw-mapreduce プラグインが有効である場合、 mapreduceCompileBatchapps タスクの生成物がjarファイルの内容に追加される。

規約プロパティ拡張

Batch Application Plugin ( asakusafw ) への拡張

Asakusa on MapReduce Gradle Pluginは Batch Application Plugin に対して Asakusa on MapReduceのビルド設定を行うための規約プロパティを追加します。この規約プロパティは、 asakusafw ブロック内の参照名 mapreduce でアクセスできます [3] 。

以下、 build.gradle の設定例です。

build.gradle

asakusafw {
    mapreduce {
        include 'com.example.batch.*'
        option 'hashJoinForTiny', 'false'
    }

この規約オブジェクトは以下のプロパティを持ちます。

mapreduce.version

Asakusa on MapReduceのコンポーネントバージョンを保持する。

この値は設定による変更は不可。

既定値: Asakusa on MapReduce Gradle Pluginが保持する既定のバージョン

mapreduce.outputDirectory

コンパイラの出力先を指定する。

文字列や java.io.File などで指定し、相対パスが指定された場合にはプロジェクトからの相対パスとして取り扱う。

既定値: "$buildDir/batchc"

mapreduce.include

コンパイルの対象に含めるバッチクラス名のパターンを指定する。

バッチクラス名には * でワイルドカードを含めることが可能。

また、バッチクラス名のリストを指定した場合、それらのパターンのいずれかにマッチしたバッチクラスのみをコンパイルの対象に含める。

既定値: null (すべて)

mapreduce.exclude

コンパイルの対象から除外するバッチクラス名のパターンを指定する。

バッチクラス名には * でワイルドカードを含めることが可能。

また、バッチクラス名のリストを指定した場合、それらのパターンのいずれかにマッチしたバッチクラスをコンパイルの対象から除外する。

include と exclude がいずれも指定された場合、 exclude のパターンを優先して取り扱う。

既定値: null (除外しない)

mapreduce.runtimeWorkingDirectory

実行時のテンポラリワーキングディレクトリのパスを指定する。

パスにはURIやカレントワーキングディレクトリからの相対パスを指定可能。

未指定の場合、コンパイラの標準設定である「 target/hadoopwork 」を利用する。

既定値: null (コンパイラの標準設定を利用する)

mapreduce.option

コンパイラプロパティ （コンパイラのオプション設定）を追加する。

後述する コンパイラプロパティ を <key>, <value> の形式で指定する [4] 。

既定値: (MapReduce向けのコンパイルに必要な最低限のもの)

mapreduce.failOnError

MapReduce向けのコンパイルを行う際に、コンパイルエラーが発生したら即座にコンパイルを停止するかどうかを選択する。

コンパイルエラーが発生した際に、 true を指定した場合にはコンパイルをすぐに停止し、 false を指定した場合には最後までコンパイルを実施する。

既定値: true (即座にコンパイルを停止する)

[3]	これらのプロパティは規約オブジェクト com.asakusafw.gradle.plugins.AsakusafwCompilerExtension が提供します。

[4]	コンパイラプロパティを指定する方法は他にいくつかの方法があります。詳しくは com.asakusafw.gradle.plugins.AsakusafwCompilerExtension のメソッドの説明を参照してください。

Framework Organizer Plugin ( asakusafwOrganizer ) への拡張

Asakusa on MapReduce Gradle Plugin は Framework Organizer Plugin に対して Asakusa on MapReduceのビルド設定を行うための規約プロパティを追加します。この規約プロパティは、 asakusafwOrganizer ブロック内の参照名 mapreduce でアクセスできます [5] 。

この規約オブジェクトは以下のプロパティを持ちます。

mapreduce.enabled

デプロイメントアーカイブにMapReduce向けのバッチアプリケーションを実行するためのコンポーネントを追加するかどうかを指定する (各プロファイルのデフォルト値)。

true を指定した場合にはコンポーネントを追加し、 false を指定した場合には追加しない。

既定値: true (コンポーネントを追加する)

<profile>.mapreduce.enabled

対象のプロファイルに対し、デプロイメントアーカイブにMapReduce向けのバッチアプリケーションを実行するためのコンポーネントを追加するかどうかを指定する。

前述の mapreduce.enabled と同様だが、こちらはプロファイルごとに指定できる。

既定値: asakusafwOrganizer.mapreduce.enabled (全体のデフォルト値を利用する)

[5]	これらのプロパティは規約オブジェクト com.asakusafw.mapreduce.gradle.plugins.AsakusafwOrganizerMapReduceExtension が提供します。

コマンドラインオプション

mapreduceCompileBatchapps タスクを指定して gradlew コマンドを実行する際に、 mapreduceCompileBatchapps --update <バッチクラス名> と指定することで、指定したバッチクラス名のみをバッチコンパイルすることができます。

また、バッチクラス名の文字列には * をワイルドカードとして使用することもできます。

以下の例では、パッケージ名に com.example.target.batch を含むバッチクラスのみをバッチコンパイルしてデプロイメントアーカイブを作成しています。

./gradlew mapreduceCompileBatchapps --update com.example.target.batch.* assemble

そのほか、 mapreduceCompileBatchapps タスクは gradlew コマンド実行時に以下のコマンドライン引数を指定することができます。

--options <k1=v1[,k2=v2[,...]]>

追加のコンパイラプロパティを指定する。

規約プロパティ asakusafw.mapreduce.option で設定したものと同じキーを指定した場合、それらを上書きする。

--fail-on-error <"true"|"false">

コンパイルエラー発生時に即座にコンパイル処理を停止するかどうか。

規約プロパティ asakusafw.mapreduce.failOnError の設定を上書きする。

--update <batch-class-name-pattern>

指定のバッチクラスだけをコンパイルする (指定したもの以外はそのまま残る)。

規約プロパティ asakusafw.mapreduce.{in,ex}clude と同様にワイルドカードを利用可能。

このオプションが設定された場合、規約プロパティ asakusafw.mapreduce.{in,ex}clude の設定は無視する。

Asakusa DSL Compiler for MapReduce リファレンス

コンパイラプロパティ

Asakusa DSL Compiler for MapReduceで利用可能なコンパイラプロパティについて説明します。これらの設定方法については、 Batch Application Plugin ( asakusafw ) への拡張 の mapreduce.option の項を参照してください。

Asakusa DSL Compiler for MapReduce - コンパイルオプション

項目名	既定値	概要
enableCombiner	無効	部分集約 [6] の既定値。 部分集約を許す演算子に対して PartialAggregation.DEFAULT が [7] 指定された場合に、このオプションが有効であれば部分集約を行い、そうでなければ行わない。
compressFlowPart	有効	ステージ数が少なくなる方法でフロー演算子を展開する。 このオプションが無効であればフロー演算子の展開時に全ての入出力にチェックポイント演算子を挿入する。 このオプションが有効であれば、展開時に何も挿入しない。
compressConcurrentStage	有効	互いに影響のないステージを1つのステージに合成する。 このオプションが有効であれば、互いに依存関係のない2つ以上のステージを単一のステージに合成し、無効であれば合成しない。
hashJoinForTiny	有効	データサイズに DataSize.TINY と指定したジョブフローの入力をマスタとして結合する際に、可能であればハッシュ表での結合を行う。 このオプションが有効であれば上記の動作を行い、無効であればコンパイラが自動的に結合戦略を決定する。
hashJoinForSmall	無効	将来の拡張のためにリザーブされた項目。現在は動作に影響しない。
enableDebugLogging	無効	Logging.Level.DEBUG が指定されたロギング演算子を利用可能にする。 このオプションが有効であれば、そのようなロギング演算子をコンパイル後も保持する。 無効であれば、コンパイル時にそれらの演算子を除去する。

上記の他に、 X から始まるいくつかの コンパイラスイッチ も存在します。 コンパイラスイッチもコンパイルオプションと同じシステムプロパティを利用します。

Note

compressFlowPart の既定値は0.2から「有効」に変更しました。 チェックポイント演算子はMapReduceの単位 (ステージ) に区切りをいれる演算子で、元は「フロー部品のテスト時とできるだけ同じ構造にしたほうが良い」という前提でこのオプションを無効化していました。 しかし、あまりにMapReduceの回数が増えてしまい、処理効率が著しく低下するため、0.2よりこの規定値が見直されることになりました。

Note

compressConcurrentStage は利点と欠点のある最適化です。 この最適化により、ステージ数は最小で「クリティカルパスのステージ数」まで低下します。 しかし、ここで合成されるステージは本来互いに影響がありませんので、Hadoopはこれらのステージを同時に処理することが可能です。

この最適化の欠点は、時間のかかるステージとかからないステージを合成してしまうと、後者のステージが本来先に終わる場合でも、前者のステージの処理が完了するまで余計な待ち合わせが発生してしまう点です。 Hadoopクラスターが十分に大きく、ワークフローエンジンが並列のジョブ投入をサポートしている場合は、このオプションは見直すべきでしょう。

Note

hashJoinForTiny は、Hadoopの DistributedCache の仕組みを利用しています。 ハッシュ表での結合を行う場合、入力データをHadoopクラスターの全てのノードに配布します。 そこでハッシュ表を構築し、タスクのメモリ上に保持します。

現在の標準的な結合戦略はShuffle+Sortを利用したマージ結合であるため、これは結合操作を行うたびにReduceフェーズが必要になってしまいます。 結果としてMapReduceのステージ数が増大してしまいますが、ハッシュ表を利用する場合には全てのノードのメモリ上に表を構築しているため、Reduce処理が不要になり、ステージ数を削減できるという利点があります。

ただし、およそハッシュ表の元になったデータサイズの倍程度のメモリを必要とするため、適用範囲が限られてしまうという問題はあります。

[6]	部分集約の設定については、 演算子リファレンス の単純集計演算子や畳み込み演算子を参照してください。

[7]	com.asakusafw.vocabulary.flow.processor.PartialAggregation

コンパイラスイッチ

コンパイラスイッチはコンパイラの内部的な挙動を操作するためのオプションで、 コンパイラプロパティ と同様の方法で設定します。

Hint

通常の場合、コンパイラスイッチを指定する必要はありません。 コンパイル時にコンパイラから推奨される場合がありますので、その際に利用を検討してください。

すべてのコンパイラスイッチは X<項目名>=<値> の形式で設定します。 以下は変更可能なコンパイラスイッチの一覧です。

コンパイラスイッチの項目

項目名	既定値	概要
MAPREDUCE-370	DISABLED	利用中のHadoopにパッチ MAPREDUCE-370 が適用済みかどうか。 ENABLED の場合は適用済みと仮定し、 DISABLED の場合は未適用と仮定する。
compressFlowBlockGroup	ENABLED	コンパイラプロパティ の compressConcurrentStage を適用した際、ステージ内のMapperとReducerを併合するかどうか。 ENABLED の場合は併合し、 DISABLED の場合は併合しない。
packaging	ENABLED	アプリケーションのパッケージングを行うかどうか。
javaVersion	1.8 [8]	DSLコンパイラがコンパイル時に指定するJavaのバージョン

Tip

コンパイルオプションは項目名を間違えた場合にエラーとなりますが、コンパイラスイッチは項目名を間違えると単に設定が無視されます。

[8]	Asakusa Gradle Plugin ユーザーガイド に従ってアプリケーションプロジェクトを作成した場合は、Gradle Pluginの設定値が適用されます。詳しくは Asakusa Gradle Plugin リファレンス を参照してください。