非同期アプリケーションのためのJavaエージェントAPI

以下のコードスニペットのメソッドparallelStream()について考えてみます。requestItemAsync()への呼び出しの一部は別のスレッドで発生するため、トークンが作成されて渡され、その非同期作業を要求元のスレッドにリンクします。

/**
* Example showing multi-threaded implementation of requesting data using a parallel {@link Stream}.
*/
@RequestMapping("parallel_stream")
@Trace(dispatcher = true) // starts a transaction
public ResponseEntity<String> parallelStream(@RequestParam("ids") List<Long> ids) {
    final Token token = NewRelic.getAgent().getTransaction().getToken();
    List<item> results = ids
            .parallelStream()
            .map(id -> requestItemAsync(id, token)) // requestItemAsync represents an  example of work being passed to another thread. The token is passed along to allow linking the work on the new thread back to the thread that the token was originally created on.
            .filter(item -> item != null)
            .collect(Collectors.toList());
    token.expire();
    return formattedResponse("parallel_stream", results);
}

本サンプルでのエージェントAPIコールは

• @Trace(dispatcher = true)：エージェントにトランザクションを開始するように指示します。このメソッドの詳細については、 Javadocを参照してください。
• getToken()：作業をリンクするトークンを作成します。このメソッドの詳細については、 Javadocを参照してください。
• token.expire()：トークンを期限切れにします。これにより、トランザクションを終了できます。このメソッドの詳細については、 Javadocを参照してください。

次のコード例はrequestItemAsyncを示しています。これは、要求元のスレッドとは別のスレッドで実行される可能性があります。このため、前のコード例で作成されたトークンは、 requestItemAsyncのトランザクションにリンクされています。requestItemAsync()には@Trace(async=true)アノテーションが付いていることに注意してください。これは、既存のトランザクションにリンクされている場合にこのメソッドをトレースするようにエージェントに指示します。

parallelStream()がすべての結果を収集した後、トークンは期限切れになります。これは、 parallelStream()の完了後にトランザクションが開いたままにならないようにするために重要です。

@Trace(async = true)
private Item requestItemAsync(long id, Token token) {
    token.link();
    return requestItem(id);
}

本サンプルでのエージェントAPIコールは

• @Trace(async = true)：トランザクションを開始します。このメソッドの詳細については、 Javadocを参照してください。
• token.link()： requestItemAsync()で実行されている作業（別のスレッドで実行されている）を要求元のスレッドにリンクします。このメソッドの詳細については、Javadocを参照してください。

トレースの詳細を表示するには、 one.newrelic.com APM & services > (select an app) > Transactions > Transaction trace > Trace detailsにアクセスしてください。

非同期アクティビティは、時間ディメンションで水平方向に重なり合うセグメントによってトレース ウォーターフォール ビューに表示されます。

同じスレッドにあるメソッドをリンクする必要はありませんが、リンクしても悪影響はありません。parallelStream()の例のように、単一のトークンを共有できる場合がよくあります。

以下のメソッドは、メソッドstoreItem()を使用して外部サービス（この場合はデータベース）を呼び出します。

/**
* Example showing single threaded implementation of inserting data into a datasource.
*/
@RequestMapping("insert")
@Trace(dispatcher = true) //starts a transaction
public ResponseEntity insert(@RequestParam("id") Long id) {
    if (id != null) {
        storeItem(id);
        return new ResponseEntity<>("insert", HttpStatus.OK);
    } else {
        return new ResponseEntity<>("insert", HttpStatus.BAD_REQUEST);
    }
}

この場合の目標は、 storeItem()の実行時間を決定するのではなく、LambdaステートメントのCallableが実行前にスレッドプールで待機している時間を調べることです。このため、トークンの代わりにセグメントが使用され、トークンの場合のように@Trace(async = true)は必要ありません。

このサンプルでのエージェントのAPIコールは

• @Trace(dispatcher = true)：トランザクションを開始します。このメソッドの詳細については、 Javadocを参照してください。

次のコード例は、 storeItemメソッドで開始し、Lambda ステートメントがスレッド プールで待機している時間を測定するセグメントを示しています。 セグメントのタイミングを停止するには、 .end()または.ignore()いずれかを呼び出す必要があります。 don'tセグメントを親トランザクションの一部としてレポートする場合は、 .ignore()を呼び出します。 それ以外の場合、セグメントを親トランザクションの一部として報告するには、 .end()を呼び出します。

private void storeItem(long id) {
    Segment segment = NewRelic.getAgent().getTransaction().startSegment("storeItem");

    segment.reportAsExternal(DatastoreParameters
           .product("H2")
           .collection(null)
           .operation("insert")
           .instance("localhost", 8080)
           .databaseName("test")
           .build());

    // fire and forget
    DB_POOL.submit(() -> {
        segment.end();
        insertData(id);
    });
}

本サンプルでのエージェントAPIコールは

• startSegment(...)：コードの時間を計測するセグメントを開始します。このメソッドの詳細については、 Javadocを参照してください。
• reportAsExternal(DatastoreParameters())：時刻をデータストアの外部呼び出しに関連付けます。これは、APMに データストアデータとともに表示されます。詳細については、 reportAsExternalAPIを参照してください。
• segment.end()：このセグメントのタイミングを停止します。このメソッドの詳細については、 Javadocを参照してください。

メソッドが完了すると、APM は 1 つの外部呼び出しを含むトランザクション追跡を表示します。