World Map
Java Service Wrapperは、御社Javaアプリケーション製品の安定した信頼性を高める最短最善の方法です。
  • Free Trial
  • Buy Now
wrapper.filter.<x>.<n> プロパティ

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/OSIBM 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/OSIBM z/Linux

このプロパティには、実行するアクションを指定します。 このプロパティは必須です。

もしアクションが省略されていた場合、 デフォルトの [RESTART] のアクションが実行されます。

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

可能なアクションは次のとおり：

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

    デバッグメッセージをログ化します。 これは、アクションの発生を把握できるので、とても役立ちます。

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

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

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

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

  • [RESTART] ：

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

  • [SHUTDOWN] ：

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

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

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

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

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

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

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

  • [SUCCESS] (ver. 3.5.5から) ：

    起動失敗の内部カウントをリセットして、 現在のJVM起動が成功したものとしてカウントします。 これは、比較的、短い頻度で再起動するように設計されたアプリケーションに便利です。

  • [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/OSIBM z/Linux

このプロパティには、［wrapper.filter.trigger.<n>］ プロパティに設定するトリガー文字にワイルドカードを「利用する (TRUE)／利用しない (FALSE)」を設定します。 もしTUREに設定すると、 ［wrapper.filter.trigger.<n>］ フィルターに含まれているワイルドカードを処理します。詳しくは下記の使用例を参照ください。

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

注意

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

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

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

設定例： 
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
出力例： 
jvm 1    | 次のラインで、WrapperがJVMを再起動させるはず:
jvm 1    |   エラー
wrapper  | フィルタートリガーが一致しました。JVM再起動中。
wrapper  | JVM起動中...
jvm 2    | WrapperManager: 初期化中...

ワイルドカードの利用：

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

設定例： 
wrapper.filter.trigger.1=Head*Tail-?
wrapper.filter.allow_wildcards.1=TRUE
wrapper.filter.action.1=RESTART
出力例： 
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
出力例： 
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: 初期化中...

例外に一致させる方法：

多くの場合、ある文字列のトリガーロジックを書きたいが、 ある文字列に発見した場合は無視したい（例外処理）、というケースです。

トリガーは「<n>」番号の順に処理されます。 一旦、トリガーが一致すると、それ以降を無視します。 これで、例外処理の一致を設定することが可能です。

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

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

「OutOfMemoryError」検知：

注意

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

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

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

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

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

設定例： 
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. JVM再起動中。
jvm 1    |  188:             8            384  java.io.OutputStreamWriter
jvm 1    |  189:             1            376  java.awt.Checkbox

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

設定例： 
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.
出力例： 
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全体のコンフィギュレーションを印刷した場合、 次のような出力になるでしょう。

出力例： 
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.

Copyright (c) 2004-2019, Tanuki Software, Ltd. All Rights Reserved.