Nde.jsエージェントAPIユーザーガイド

Related pages:

Web アプリケーションが、HTTP 要求または Web ベースではないアプリケーションのコンテキスト外で実行するビジネストランザクションをモニタする場合は、 Node.js Agent を AppDynamics Node.js エージェント API で有効にします。

ビジネストランザクションの定義

appd.startTransaction() および end() を使用してカスタムビジネストランザクションを定義します。

カスタムトランザクションが長時間実行されている場合、または非同期境界を超えている場合は、resume() を使用して実行中のトランザクションを再結合できます。

分散トランザクションにおけるダウンストリームトランザクションは、アップストリームトランザクションが終了コールを行うまで開始することができません。

トランザクションの順序は、Node.jsアプリケーションの非線形性を尊重します。アップストリームトランザクションは、終了コールが完了した直後、またはしばらくしてから終了する場合があります。アップストリームトランザクションは、ダウンストリームトランザクションが開始または終了する前後で終了する必要はありません。ダウンストリームトランザクションは、アップストリームトランザクションが終了する前に終了する可能性があります。

トランザクションをエラートランザクションとしてマークする

エラートランザクションは、例外が発生したトランザクションです。エラーが発生したトランザクションが遅い場合や停滞している場合でも、遅い、非常に遅い、または停滞しているトランザクションではなく、エラートランザクションとして報告されます。

Node.js APIを使用してJavaScriptエラーオブジェクトをトランザクションに添付するには、次のいずれかの操作を行います。

JavaScript エラーオブジェクトを渡す trx.markError() を使用する。
エラーオブジェクトをトランザクションに関連付けられたHTTP応答にresponse.errorとして添付する。

エラーがマークされると、以下のいずれかの方法で設定しない限り、ステータスコードはデフォルトの 500 となります。

JavaScript エラーオブジェクトおよびオプションのステータスコードを渡す trx.markError() を使用。
trx.markError() に error.StatusCode として渡されるエラーオブジェクトの statusCode プロパティを設定。
response.error オブジェクトの statusCode プロパティを response.error.StatusCode として設定。

トランザクション相関管理

トランザクション相関とは、分散トランザクションが横切るすべてのティア（サーバ）にわたり、ビジネストランザクションコンテキストを維持する機能のことです。ティアはNode.js以外のプラットフォームで構築することもできます。たとえば、Java、.NET、および PHP のティアは、Node.js ティアが参加する分散型ビジネストランザクションに、トランザクションの開始、継続、または終了のティアとして参加できます。

Node.jsエージェントAPIは、さまざまなトランザクション間のトランザクション相関を管理する機能を提供します。これはカスタムまたは自動で検出される場合があります。

AppDynamics のデフォルト自動検出メカニズムは、受信 HTTP 要求からトランザクションの相関情報を取得しますが、Node.js エージェント API を使用すると、Redis キャッシュエントリのカスタムフィールドなど、他のソースからこの情報を取得し、カスタムトランザクションに適用できます。APIを使用すると、ダウンストリームトランザクションに対して行う終了コールでトランザクションの相関情報を提供することにより、前方相関に対応することができます。

ダウンストリームトランザクションは、すぐアップストリームトランザクションが終了コールを行った後に開始します。コールはメッセージキューの発行など、何らかの処理を行うバックエンドサービスへの呼び出しまたは次のティアへの直接的な終了コールである場合があります。

。 Transaction Correlation

終了コールの管理

終了コールは、カスタム終了コールまたは自動検出された終了コールのいずれかになります。トランザクションは、関連する必要があるダウンストリームトランザクションに提供する相関情報を作成するため、その終了コールオブジェクトを必要とします。

カスタム終了コール

終了コールをコントローラに報告する場合で、エージェントが自動検出しない場合は、startExitCall() でカスタム終了コールを作成し、endExitCall() で終了します。

次のエージェントで自動検出されないバックエンドの一覧については、「Node.js対応環境」を参照してください。 Node.js Agent。終了コールがこのページに記載されていないバックエンドを呼び出すには、カスタム終了コールを作成する必要が出てくるでしょう。

beforeExitCall() コールバック関数を使用して、自動検出された終了コールの存在を確認することもできます。

カスタム終了コールの処理は難しくありません。最初に終了コールを作成し、返された ExitCall オブジェクトを createCorrelationInfo() に渡し、ダウンストリームトランザクションが後で取り出せる文字列エンコード相関情報オブジェクトを作成します。

Workflow for a custom exit call

// start a custom transaction
var trx = appd.startTransaction(. . . )
. . . 

// start a custom exit call
exit = trx.startExitCall(. . .);

// create correlation information
cinfo = trx.createCorrelationInfo(exit)
//store cinfo where it can be made available to a downstream transaction

// make the exit call
. . . 
trx.endExitCall(. . .)

CODE

自動検出された終了コール

カスタムトランザクションで実行されるコードは、次のエージェントが自動検出する終了コールを行う場合があります。 Node.js Agent。

この場合、beforeExitCall() コールバック関数を使用して、その終了コールを処理できます。コードで自動検出された終了コールが行われると、エージェントは終了コールの要求を傍受し、コールバックを提供している場合はコールバックを呼び出します。その後アプリケーションは終了コール要求を処理することができます。

beforeExitCall() コールバック関数のインストールは以下の目的で行います。

自動検出された終了コールの存在を確認
終了コールが自動検出されるか定かでない場合、コールバック関数をインストールして終了コールをテストすることができます。コールバックが呼び出されない場合、終了コールは自動検出されません。
```
// start a custom transaction
var trx = appd.startTransaction(. . . )
. . . 

var detected = false;
trx.beforeExitCall = function(call) { detected = true; return call; };

// make the exit call
. . . 

// test whether the exit call was automatically detected
if (detected == false)
. . . 
```
CODE
終了コールの後も detected が false の場合は、カスタム終了コールを作成して終了コールをコントローラに報告する必要があります。detected が true の場合は、終了コールを取得し、コールバックを使用して相関情報を作成できます。

ExitCallオブジェクトを取得して相関情報を作成

// start a custom transaction
var trx = appd.startTransaction(. . . )
. . . 

trx.beforeExitCall = function getExitInfo(exitCall) { 
    // create the correlation header from the captured exit call 
    var c = trx.createCorrelationInfo(exitCall); 
    // store c somewhere
    // … (c)  
    return exitCall; 
} 
// make the exit call

CODE

コントローラに報告する終了コールを変更するには

// start a custom transaction
var trx = appd.startTransaction(. . . )
. . . 

trx.beforeExitCall = function customExitCallHandler(exitCall) {
    // don't report database access for this transaction
    if (exitCall.isSql) return; 
    // customize label for all other exit calls in this transaction
    exitCall.label += " (my custom transaction)";
    return exitCall;
}
// make the exit call

JS

ワークフロー：相関情報を使用して元のトランザクションを作成

このシナリオでは、カスタム開始トランザクションと、ダウンストリームトランザクションが関連付ける必要のある相関ヘッダーを作成します。

カスタムトランザクションを開始：var trx=appd.startTransaction(...)。
e=trx.startExitCall(einfo) を使用してカスタム終了コールを開始するか、e=trx.beforeExitCall(e) にコールバック関数をインストールして検出された終了コールを取得。
終了コールから相関情報を作成：c=trx.createCorrelationInfo(e)。
相関情報を保存。
終了コールを作成。
終了コールの実行により取得した情報に基づき、コントローラに報告する内容を変更する場合は、オプションで trx.exitCallCompleted(e) コールバック関数を指定。
カスタム終了コールを作成した場合は、終了コールの応答を処理した後に終了コールを終了：trx.endExitCall(e)。
トランザクションを終了：trx.end()。

ワークフロー：アップストリームトランザクションと関連する終了トランザクションの作成

このシナリオでは、カスタムトランザクションを作成します。カスタムトランザクションはアップストリームのトランザクションと関連付ける必要がありますが、別のダウンストリームトランザクションと関連付ける必要はありません。

以前のトランザクションで保存された相関情報を取得。
取得した相関情報を解析して相関ヘッダーを作成：ch=appd.parseCorrelationInfo(c)。
相関ヘッダーを使用してカスタムトランザクションを開始： trx=appd.startTransaction(ch)。
必要に応じて終了コールを作成。
トランザクションを終了：trx.end()。

ワークフロー：アップストリームトランザクションとダウンストリームトランザクションに関連する継続的トランザクションの作成

このシナリオでは、アップストリーム開始トランザクションとダウンストリームトランザクションの両方と相関する必要がある継続トランザクションを作成します。これには前の2つのワークフローで説明した相関方法を使用します。

以前のトランザクションで保存された相関情報を取得。
取得した相関情報を解析して相関ヘッダーを作成：ch=appd.parseCorrelationInfo(c1)。
相関ヘッダーを使用してカスタムトランザクションを開始： trx=appd.startTransaction(ch)。
e=trx.startExitCall(einfo) を使用してカスタム終了コールを開始するか、e=trx.beforeExitCall(e) にコールバック関数をインストールして検出された終了コールを取得。
このトランザクションの終了コールから相関情報を作成：c2=trx.createCorrelationInfo(e)。
次のダウンストリームトランザクションのために相関情報を保存。
終了コールを作成。
終了コールの実行により取得した情報に基づき、コントローラに報告する内容を変更する場合は、オプションで trx.exitCallCompleted(e) コールバック関数を指定。
カスタム終了コールを作成した場合は、終了コールの応答を処理した後に終了コールを終了：trx.endExitCall(e)。
トランザクションを終了：trx.end()。