wrapper.filter.<x>.<n> プロパティ群の概要

このフィルターは、とても強力な機能で、何もコーディングを必要とせず、 存在するアプリケーションに対する新しい動作を追加するなどが可能です。 JVM のコンソール出力の文字列をモニタリング（監視）することで動作し、 該当する文字列が見つかると、いくつでもアクションを実行することができます。

例えば、エラーが発生したとき JVM を再起動させます。 一部のアプリケーションには、「特定の状態になると動作を停止する」という既知のバグがあります。 このフィルター機能を活用すると、 アプリケーションの問題を解決するまで「停止する」という問題を即に回避することが可能になります。

フィルター定義に利用するプロパティは、次のとおりです。

フィルター定義として、最低でも、 ［wrapper.filter.trigger.<n>］プロパティや ［wrapper.filter.action.<n>］プロパティを 設定しなければなりません。その他のプロパティは任意に応じて設定します。

<n> コンポーネント部：

各フィルターで、 プロパティ名の「<n>」コンポーネント部には、 「1」からカウントアップしていくインテージャー（整数値）のナンバリング数値を入れて指定します。 デフォルトでは、連番であり、欠番で飛ぶことはできないはずです。 ［wrapper.ignore_sequence_gaps］ プロパティで、シーケンス内でギャップ（途切れ）検索を「許可する／許可しない」を任意に設定にすることができます。

「<n>」番号の昇順で、定義されたフィルターをスキャンします。 一つのフィルター条件が一致すると、その出力ラインで処理を停止します。

いろいろなプロパティの使用例をご紹介していますので参照ください。

wrapper.filter.trigger.<n> プロパテ
対応バージョン :3.0.0
対応エディション :プロフェッショナル版スタンダード版コミュニティー版
対応プラットフォーム :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

このプロパティには、トリガー（キッカケになるもの）の文字列を設定します。 トリガーは任意の文字列にすることができ、その構成には次のプロパティが必要です。

設定例： 
wrapper.filter.trigger.1=Error
wrapper.filter.action.1=RESTART

トリガーにスペースを含む：

フィルタリングされる文字列にはスペース（空白）を含めることができます。 しかし、一般的にコンフィギュレーションプロパティがロード（読み込み）される処理において、 先頭や末尾にあるスペース（空白）はトリム（切り落とし）されます。

設定例： 
wrapper.filter.trigger.1=  Restart me now.
wrapper.filter.action.1=RESTART

ワイルドカード：

Wrapper バージョン 3.5.5 から、 ［wrapper.filter.allow_wildcards.<n>］プロパティを「TRUE」に設定した場合、 トリガー文字にワイルドカード（「*」や「?」）を含めることが可能です。

有効なワイルドカード文字は次のとおりです。

  • 「*」文字は、「0（ゼロ）」か任意の文字列に相当します。
  • 「?」文字は、キッチリ１文字に相当します。

注意

トリガー値は、出力の一行内のどこかに配置されている文字列として検索されますので、 トリガー値の前後に「*」ワイルドカードをつける必要はありません。 もし、そうすると、パターン一致の処理が複雑化し、 「ログ出力の一行の中に指定されたトリガーが見つからない」と判定するまでに時間を要し、 実際にはログのパフォーマンスが低下することがあるのでご了解ください。

wrapper.filter.action.<n> プロパティ群
対応バージョン :3.0.0
対応エディション :プロフェッショナル版スタンダード版コミュニティー版
対応プラットフォーム :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

アクションを実行するには、このプロパティを設定する必須があります。 もしアクションが省略されていた場合、デフォルトの [RESTART] のアクションが実行されます。

設定例： 
wrapper.filter.trigger.1=Error
wrapper.filter.action.1=RESTART

可能なアクションは次のとおりです。

  • [DEBUG] （ver. 3.5.0 から）：

    デバッグメッセージをログ化します。 これは、アクションがいつ発生されるかを把握するのに役立ちます。

  • [STATS] （ver. 3.5.52 から）（スタンダード版、プロフェッショナル版）：

    パフォーマンス統計情報を出力します。

  • [DUMP] （ver. 3.3.6 から）：

    スレッドダンプを生成します。

  • [GC] （ver. 3.5.7) から）：

    JVM で完全なガベージコレクション掃除を実行します。 完全な掃除をすると、ガベージコレクション中、しばしば全てのスレッドがフリーズしたりなど引き起こすため、 これを頻繁にすると JVM のパフォーマンスに影響しますのでご理解ください。

  • [RESTART] ：

    現在の JVM を停止して、新しい「起動の試み（invocation）」として再起動します。

  • [SHUTDOWN] ：

    Wrapper 同様に、JVM を終了します。

  • [USER_<n>] （ver. 3.5.0 から）（プロフェッショナル版）：

    ユーザー定義イベントを発生させます。 イベントには、「メール送信」か、 or 「外部システムコマンドの実行」どちらかのアクションが可能です。 そのコマンド指定には、クリーンアップ作業や SNMP トラップを起こしたり、何でも可能です。

  • [PAUSE] （ver. 3.5.0 から）：

    ポーズ（一時停止）が可能で JVM が動作している場合、Java アプリケーションを一時停止します。 詳しくは［wrapper.pausable］プロパティをご覧ください。

  • [RESUME] （ver. 3.5.0から）：

    JVM が一時停止状態にあるとき、Java アプリケーションを再開します。 これは、JVM が停止ではなく一時停止している場合に利用可能です。 詳しくは［wrapper.pausable］プロパティをご覧ください。

  • [SUSPEND_TIMEOUTS_<n>] （ver. 3.5.40 から）（スタンダード版、プロフェッショナル版）：

    JVM が応答しない場合、全てのタイムアウトを停止するように指示します。 「<n>」は、タイムアウトを停止する期間（秒数）を指定し、1-3600（１秒から１時間まで）の範囲で設定できます。 これは、Java アプリケーションが長いブロックタスクを実行する必要がある時に Wrapper がアプリケーションが応答不能と判断するのを防ぐために使用できます。

    その他のアクションプロパティ、コマンドファイル、或いは Java WrapperManager.suspendTimeouts() メソッドでタイムアウトを停止することができます。

    タイムアウトを停止するリクエストが複数ある場合、各リクエストで指定されている秒数は加算されません。 代わりに、新しく指定された秒数が残りの停止期間より長い場合、停止期間が置き換えられますが、 それより短い場合は無視されます。

  • [RESUME_TIMEOUTS] （ver. 3.5.40 から）（スタンダード版、プロフェッショナル版）：

    Wrapper に、停止された全てのタイムアウトを再開するように指示します。

    その他のアクションプロパティ、コマンドファイル、或いは Java WrapperManager.resumeTimeouts() メソッドでタイムアウトを再開することができます。

  • [NONE] ：

    高いナンバリング数値で設定されているトリガーを、フィルター検索の対象から除外することができるので、便利です。

複数のアクションを指定する：

Wrapper バージョン 3.5.0 から、スペースやカンマで区切ることで、複数のアクションを指定することが可能です。 複数のアクションを指定すると、迅速に指定した順番で続けて実行されます。

次の例では、トリガー条件に一致した場合、スレッドダンプを実行して、その後、JVM を再起動します。

設定例： 
wrapper.filter.trigger.1=Error
wrapper.filter.action.1=DUMP,RESTART

wrapper.filter.allow_wildcards.<n> プロパティ群
対応バージョン :3.5.5
対応エディション :プロフェッショナル版スタンダード版コミュニティー版
対応プラットフォーム :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

「TRUE」に設定されている場合、このプロパティは、フィルターのために［wrapper.filter.trigger.<n>］で見つかったすべてのワイルドカードを処理するように Wrapper に指示します。 詳しくは下記の使用例を参照ください。

>設定例： 
wrapper.filter.allow_wildcards.1=TRUE

注意

利用することは構わないのですが、ワイルドカードを含むトリガー文字を検索することは、CPU に負荷を強いることになります。 これは特に長い出力行を伴う場合に、トリガーのワイルドカードがトリガーの冒頭に設定されているとき、顕著に表れます。 同じトリガーの中に複数のワイルドカードを利用すると、 全ての組み合わせでパターン一致を検索することになるため、動作がスローダウンします。

wrapper.filter.message.<n> プロパティ群
対応バージョン :3.5.0
対応エディション :プロフェッショナル版スタンダード版コミュニティー版
対応プラットフォーム :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

この［wrapper.filter.message.<n>］プロパティには、トリガーが発生したとき、ユーザーに表示するメッセージを設定します。 何が起きているのか、ユーザーに説明するのに、とても便利です。 デフォルト値は「Filter trigger matched」です。

Example: 
wrapper.filter.trigger.1=java.lang.OutOfMemoryError
wrapper.filter.action.1=RESTART
wrapper.filter.message.1=The JVM has run out of memory.

使用例：

このセクションでは、トリガーを最大に活かす様々な使用例ご紹介します。 フィルターは、JVM のコンソール出力をモニタリング（監視）することで動作します。 トリガーが例外で発動されるようにするために、 Java アプリケーションが、コンソールへフィルタリングされたメッセージを表示しなければなりません。

シンプル一致

多くの場合、アプリケーションからの出力に含まれる既存のメッセージに反応してアクションをトリガーしたい場合があります。

この例では、トリガー文字として「Error」キーワードが該当した場合に、JVM 再起動を引き起こします。

設定例： 
wrapper.filter.trigger.1=Error
wrapper.filter.action.1=RESTART
Wrapper 出力例： 
jvm 1    | 次のラインで、Wrapper が JVM を再起動させるはず:
jvm 1    |   エラー
wrapper  | フィルタートリガーが一致しました。JVM 再起動中。
wrapper  | JVM 起動中…
jvm 2    | WrapperManager: 初期化中…

ワイルドカードの利用

いくつかのケースでは、正確に一致する文字列が分からない場合がありますので ワイルドカードを含むトリガーを設定できることは、非常に便利です。

Example: 
wrapper.filter.trigger.1=Head*Tail-?
wrapper.filter.allow_wildcards.1=TRUE
wrapper.filter.action.1=RESTART
Wrapper 出力例： 
jvm 1    | 次のラインで、Wrapper が JVM を再起動させるはず:
jvm 1    |   Head a bunch of stuff, then Tail-1 and some more stuff.
wrapper  | フィルタートリガーが一致しました。JVM 再起動中。
wrapper  | JVM 起動中…
jvm 2    | WrapperManager: 初期化中…

複数のアクションを指定する

Wrapper バージョン 3.5.0から、 スペースやカンマで区切ることで、複数のアクションを指定することが可能です。 複数のアクションを指定すると、迅速に指定した順番で続けて実行されます。

次の例は、コンソール出力内に検知した「User Error」（ユーザーエラー）のキーワードに反応して、 スレッドダンプを実行して、その後、JVM を再起動します。

設定例： 
wrapper.filter.trigger.1=User Error
wrapper.filter.action.1=DUMP,RESTART
Example Wrapper Output: 
jvm 1    | 次のラインで、Wrapper が JVM を再起動させるはず:
jvm 1    |   User Error
wrapper  | フィルタートリガーが一致しました。  スレッドダンプをリクエスト中。
wrapper  | JVM 状況をダンピング中。
wrapper  | フィルタートリガーが一致しました。  JVM 再起動中。
jvm 1    | Full thread dump Java HotSpot(TM) Client VM (1.5.0_24-149 mixed mode, sharing):
jvm 1    | 
jvm 1    | "WrapperSimpleAppMain" prio=5 tid=0x0100f400 nid=0x86c600 waiting on condition [0xb0e8e000..0xb0e8ed90]
jvm 1    | 	at java.lang.Thread.sleep(Native Method)
jvm 1    | ...
jvm 1    | "Exception Catcher Thread" prio=10 tid=0x01001910 nid=0x80ac00 runnable 
wrapper  | JVM 起動中…
jvm 2    | WrapperManager: Initializing...

例外に一致させる方法

多くの場合、ある文字列のトリガーロジックを書きたいが、 特定のコンテキストではそれを無視したい（例外処理）ことが判明します。 トリガーは「<n>」番号の順に処理されます。 一旦、トリガーが一致すると、それ以降を無視します。 これで、例外処理の一致を設定することが可能です。

この例では、「IgnoreError」キーワードを除く 「Error」キーワードでトリガーし、JVM を再起動します。

設定例： 
wrapper.filter.trigger.1=IgnoreError
wrapper.filter.action.1=NONE
wrapper.filter.trigger.2=Error
wrapper.filter.action.2=RESTART
Wrapper 出力例： 
jvm 1    | The next line should be ignored:
jvm 1    |   IgnoreError
jvm 1    | 
jvm 1    | 次のラインで、Wrapper が JVM を再起動させるはず:
jvm 1    |   Error
wrapper  | フィルタートリガーが一致しました。  JVM 再起動中。
wrapper  | JVM 起動中…
jvm 2    | WrapperManager: 初期化中…

「OutOfMemoryError」検知

注意

Wrapper バージョン 3.5.16 から、 Wrapper コンフィギュレーションファイルのデフォルトテンプレートを更新しました。 もしユーザーが「-verbose:class」出力を有効にした場合、 フィルター機能で 「OutOfMemoryError」に一致する再起動では、 デフォルトで、もはやトリガーされなくなります。

全部まとめて、 スタックトレースに「OutOfMemoryError」が投げられたときに 検知するフィルターを作成することができます。

一番簡単な方法は、次のとおりです。

設定例： 
wrapper.filter.trigger.1=java.lang.OutOfMemoryError
wrapper.filter.action.1=RESTART

これは、「予想外の場所にクラス名が表示されると、意図としない再起動をトリガーさせる」という問題があります。 この例では、「-XX:+PrintClassHistogram」引数が JVM へ引き渡されたときであるならば、 Java は、現在メモリーにあるインスタンスの個数を表示して、 ロード（読み込み）された全てのクラスのヒストグラムを出力し、とても便利です。 Java が［OutOfMemoryError］クラスのカウントを出力すると、 上記のトリガーが JVM の再起動を引き起こします。

Example: 
jvm 1    |  186:             6            384  sun.reflect.generics.repository.MethodRepository
jvm 1    |  187:             8            384  java.lang.OutOfMemoryError
wrapper  | The JVM has run out of memory.  Restarting JVM.
jvm 1    |  188:             8            384  java.io.OutputStreamWriter
jvm 1    |  189:             1            376  java.awt.Checkbox

この回避策として、例外を設定することが可能です。 ですが、もし、 スタックトレースに表示された時にのみ ［OutOfMemoryError］クラスのトリガーをしたいと分かっている場合、 もっとフォーカスを絞ったパターン一致にワイルドカードを活用することができます。

Example: 
wrapper.filter.trigger.1=Exception in thread "*" java.lang.OutOfMemoryError
wrapper.filter.allow_wildcards.1=TRUE
wrapper.filter.action.1=RESTART
wrapper.filter.message.1=The JVM has run out of memory.
Wrapper 出力例： 
jvm 1    | Mention the java.lang.OutOfMemoryError exception (Not triggered)
jvm 1    | 
jvm 1    | Now thow a new java.lang.OutOfMemoryError to invoke a stack trace:
jvm 1    | Exception in thread "MyApp-Main" java.lang.OutOfMemoryError
wrapper  | The JVM has run out of memory.  JVM 再起動中。
jvm 1    |      場所： com.myapp.Main.doSomething(Main.java:321)
jvm 1    |      場所： com.myapp.Main.main(Main.java:654)
wrapper  | JVM 起動中…
jvm 2    | WrapperManager: 初期化中…

しかしながら、これでもまだ誤判定ポイントが一つあります。 例えば、もしユーザーが Wrapper 全体のコンフィギュレーションを出力した場合、 次のような出力になるでしょう。

Wrapper 出力例： 
jvm 1    |   wrapper.filter.trigger.1=Exception in thread "*" java.lang.OutOfMemoryError
wrapper  | The JVM has run out of memory.  JVM 再起動中。

これは、もちろん希望どおり求めるものではありませんね。 ワイルドカードを有効にせず、同じテキスト上で、プレーンテキストの一致をすると、これを避けることができます。 その例をご覧ください。

設定例： 
wrapper.filter.trigger.1=Exception in thread "*" java.lang.OutOfMemoryError
wrapper.filter.action.1=NONE

wrapper.filter.trigger.2=Exception in thread "*" java.lang.OutOfMemoryError
wrapper.filter.allow_wildcards.2=TRUE
wrapper.filter.action.2=RESTART
wrapper.filter.message.2=The JVM has run out of memory.