PreEmptive Protection - DashO v8.2 User Guide

例外レポート

PreEmptive Protection - DashO は、PreEmptive Analytics サーバーに対し、アプリケーションでスローされたハンドルされない例外を報告し、任意でメッセージを送信するようにアプリケーションをインストルメントすることができます。さらに、キャッチされた例外、キャッチされない例外、あるいはスローされた例外の報告をメソッド レベルで行うようにアプリケーションをインストルメントすることができます。例外レポートの構成は、Injection – Instrumentation パネルを使って、またはコード アノテーションを追加することにより行います。

アプリケーションおよびスレッド レベルのレポート

ハンドルされない例外をインターセプトして、アプリケーション レベルまたはスレッドごとに報告することができます。ユーザーによる操作のない非 GUI アプリケーションのために、ハンドルされない例外を直接 PreEmptive Analytics サーバーに送信することができます。GUI アプリケーションでは、アプリケーションのユーザーがレポートを送信するかどうかを選べるよう、ダイアログ ボックスが提示されるように選択することができます。また、例外が発生する前に実行していた活動に関する情報だけでなく、いくつかの連絡先情報も入力できます。この情報は任意ですが、入力すれば、PreEmptive Analytics Workbench または PreEmptive Analytics for TFS で例外情報と一緒に利用できます。

アプリケーションおよびスレッド レベルのレポートは、AddUncaughtExceptionHandler アノテーションによって追加されます。ハンドラーは、既定のハンドラーと現在のスレッド専用のいずれとしてインストールされているか、また、ユーザーにダイアログが表示されるかどうかは、アノテーションのプロパティが決定します。

@AddUncaughtExceptionHandler(showDialog=true)
public static void main(final String[] args){
    // ...
}

new Thread() {
    @AddUncaughtExceptionHandler(thread=true)
    public void run() {
        // ...
    }
}.start();

ユーザーがダイアログと対話できるようにすると、グローバルの opt-in 設定をオーバーライドする機会が与えられます。ユーザーがレポートを送信するように選択した場合は、その他の Analytics メッセージの opt-out 設定がオーバーライドされます。それでもアプリケーションは、PreEmptive Analytics サーバーでアプリケーションが識別されるようにするために、構成情報を必要とします。非 GUI アプリケーションでダイアログが要求された場合は、ユーザーがメッセージを送信するよう選択している場合にのみレポートが送信されます。

ユーザーによる操作なしでレポートを送信するよう選択した場合は、ユーザーが分析メッセージを送信するよう選択している場合にのみレポートが送信されます。

メモ:

これらの機能は、ExceptionHandler クラスの API として利用できます。

メソッド レベルのレポート

例外のレポートによりきめ細かいアプローチを求める場合は、アノテーションを使ってメソッド レベルで例外を追跡できます。DashO は、メソッド レベルの例外レポートを追加するために使用される 3 つのアノテーション、ReportCaughtExceptionsReportThrownExceptionsReportUncaughtExceptions を提供します。3 つのアノテーションはすべて次の動作をサポートしています。

  • 分析のエラー メッセージを送信する。エラー メッセージが PreEmptive Analytics サーバーへ送信されます。これは sendMessage プロパティです。既定では、メッセージを送信することになっています。メッセージを送信するには、アプリケーションに ApplicationStart が含まれており、ユーザーがメッセージを送信することを選択する必要があります。

  • メソッドを呼び出すか、またはフィールドを設定する。Throwable を取るメソッドを呼び出すか、または Throwable のフィールドを設定することによって、例外をアプリケーションに渡し返すことができます。これは action プロパティです。

どちらの動作も使用する場合は、メッセージの送信が実行されてから操作(action)が行われます。次の例は、例外のレポートがクラス内のすべてのメソッドに適用されるよう、クラス レベルに例外レポートを追加する方法を示しています。この例では、メッセージは PreEmptive Analytics サーバーへ送信されるだけでなく、Log4J を使用してローカルに記録されます。

import org.apache.log4j.Logger

@ReportCaughtExceptions(action="@onCatch()")
@ReportThrownExceptions(action="@onThrow()")
class MyClass {
    private final static Logger log = Logger.getLogger(MyClass.class)

    public void execute(){
        // ...
    }

    private static void onCatch(Throwable t){
        log.info("MyClass caught " + t.getClass().getName(), t);
    }

    private static void onThrow(Throwable t){
        log.warn("MyClass threw " + t.getClass().getName(), t);
    }
}

前述のプロパティに加え、ReportUncaughtExceptions アノテーションでも、ハンドルされない例外を無視することができます。数値を返すメソッドは、ハンドルされない例外が無視された場合にはゼロを返します。オブジェクトまたは配列を返すメソッドは、null を返します。

次の例では、div(x, 0) を呼び出すと、ArithmeticException がスローされて System.err が出力されますが、メソッドはゼロを返します。

@ReportUncaughtExceptions(sendMessage=false, action="onErr()", ignore=true)
int div(int num, int denom){
    return num / denom;
}

void onErr(Throwable t){
    t.printStackTrace();
}

PreEmptive Protection - DashO Version 8.2.0. Copyright © 2017 PreEmptive Solutions, LLC