Node.jsエージェントAPI参考資料

このページでは、Node.js エージェント API について説明します。Node.js エージェント API には、Node.js アプリケーションのビジネストランザクションとイグジットポイントを管理するためのメソッドが含まれています。 

APIコールリスト

AppDynamicsモジュールのロード

appdynamics Node.js モジュールを、appd.profile() の後の require ステートメントに追加することで、アプリケーション内で API を使用できます。

var appd = require('appdynamics');
appd.profile({ . . . })
 
...
  
var transaction = appd.startTransaction(...);
...
 

transaction.end();

ビジネストランザクション管理の基本

appd.startTransaction(transactionInfo)

• transactionInfo 文字列、HttpRequest または CorrelationHeader

transactionInfo パラメータは次のいずれかになります。

• カスタムトランザクションの名前を指定する文字列。文字 {、}、[、]、|、&、および ; は、トランザクション名に使用できません。
• HttpRequest オブジェクト。通常のトランザクション一致および命名規則が適用され、含まれるRUMおよび/またはトランザクション相関情報が自動的に選択されます。
• アップストリームにあるトランザクションと相関する情報を提供する CorrelationHeader オブジェクト。「parseCorrelationInfo()」を参照してください。

カスタム ビジネス トランザクションの作成と開始を行い、TimePromise インスタンスとしてトランザクションハンドルを返します。このトランザクションハンドルは、トランザクションの以降の操作に使用されます。

TimePromise.prototype.resume()

長期実行トランザクションまたは非同期トランザクションを再結合します。

resume() を呼び出します。

• 長期実行トランザクションをデフォルトのトランザクションタイムアウトである5分間を超えて有効にする必要がある場合。これにより、エージェントがトランザクションを失敗したとみなしてトランザクションを削除することを防げます。
• インストゥルメント中のコードが非同期境界を横切る場合。これにより、現在実行するコンテキストが正しいトランザクションに再度関連付けされ、実行したすべての終了コールが正しいトランザクションに確実に割り当てられるようにします。

TimePromise.prototype.end(error)

• error: 任意、オプション

トランザクションを終了し、トランザクション情報をコントローラに報告します。

error が渡されると、エラーがトランザクションに関連付けられ、トランザクションにはエラートランザクションとしてフラグが立てられます。

appd.getTransaction(request)

• request: HTTP 要求オブジェクト

指定の要求が存在する場合、それに関連付けられたビジネストランザクションにハンドルを返します。関連するビジネストランザクションが存在しない場合、FALSEを返します。

appd.getTransaction() を使用して、カスタムおよび自動検出されたビジネストランザクションにアクセスします。

appd.addAnalyticsData (key, value)

• key: 追加されるカスタムデータのキー
• value: このキーに追加される値

現在のトランザクション用に生成された分析にカスタムデータを添付します。アプリケーションにはトランザクションハンドルは必要ありません。

この機能を有効にするには、require ステートメントの分析設定を設定する必要があります。詳細については、Node.js設定参考資料を参照してください。分析の詳細については、「分析データソース」を参照してください。

appd.addSnapshotData (key, value)

• key: 追加されるカスタムデータのキー
• value: このキーに追加される値

現在のトランザクション用に生成されたスナップショットにカスタムデータを添付します。

addSnapshotData() はいつでもトランザクションで呼び出すことができますが、追加されたデータはトランザクション スナップショットが生成されたときのみに使用されます。トランザクション スナップショットが生成されるタイミングについては、「トランザクション スナップショットを使用したビジネス トランザクション パフォーマンスのトラブルシューティング」を参照してください。 

次の例では、スナップショットの USER DATA にセッション数を追加します。

txn.addSnapshotData(“active sessions”, my.api.getSessionCount());

トランザクション完了後にスナップショットに追加するデータが利用可能な場合は、txn.onSnapshotCaptured(txn) コールバックを使用して添付できます。この手法により、スナップショットが生成されていないときにデータを収集するためのオーバーヘッドを回避できます。カスタムデータは、コントローラ UI のトランザクション スナップショット詳細の [USER DATA] タブに表示されます。 

appd.markError(error, [statusCode])

• error:JavaScript エラーオブジェクト
• statusCode: オプションのトランザクション ステータス コード

この値は、error オブジェクトの statusCode プロパティとして渡すこともできます。

statusCode パラメータも error パラメータの error.statusCode プロパティも指定されていない場合、ステータスコードはデフォルトで 500 になります。 

ビジネストランザクションにエラーオブジェクトを付加する別の方法については、「TimePromise.prototype.end(error)」も参照してください。

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

txn.markError(error, [statusCode])

• errorJavaScript エラーオブジェクト
• statusCode オプションのトランザクション ステータス コードこの値は、error オブジェクトの statusCode プロパティとして渡すこともできます。

statusCode パラメータも error パラメータの error.statusCode プロパティも指定されていない場合、ステータスコードはデフォルトで 500 になります。 

ビジネストランザクションにエラーオブジェクトを付加する別の方法については、「TimePromise.prototype.end(error)」も参照してください。

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

txn.addSnapshotData(key, value)

• key: 追加されるカスタムデータのキー
• value: このキーに追加される値

このトランザクション用に生成されたスナップショットにカスタムデータを添付します。

addSnapshotData() はいつでもトランザクションで呼び出すことができますが、追加されたデータはトランザクション スナップショットが生成されたときのみに使用されます。トランザクション スナップショットが生成されるタイミングについては、「トランザクション スナップショットを使用したビジネス トランザクション パフォーマンスのトラブルシューティング」を参照してください。 

以下の例では、スナップショットの USER DATA にセッション数を追加します。

txn.addSnapshotData(“active sessions”, my.api.getSessionCount());

トランザクション完了後にスナップショットに追加するデータが利用可能な場合は、txn.onSnapshotCaptured(txn) コールバックを使用して添付できます。この手法により、スナップショットが生成されていないときにデータを収集するためのオーバーヘッドを回避できます。カスタムデータは、コントローラ UI のトランザクション スナップショット詳細の [USER DATA] タブに表示されます。

txn.onSnapshotCaptured(txn)

• txn：トランザクション

トランザクションスナップショットにカスタムデータを添付するのにトランザクションで設定できるコールバックメソッド。txn.addSnapshotData(key, value) で使用されます。

callback 関数を使用できる場合、エージェントはトランザクション スナップショットを取得した直後にこの API を呼び出します。 

指定すると、トランザクションがスナップショットをトリガーする場合、callback はトランザクション完了時に呼び出されます。

呼び出し関数を定義し、それをコールバックに割り当てる必要があります。

mytxn.onSnapshotCaptured = customTitle (txn) {
    // get book title for current transaction instance
    title = getBookTitle();
    txn.addSnapshotData ("book title", title);
}

txn === mytxn に注意してください。これはコールバックに渡されるため、mytxn と同じ範囲でコールバックを定義する必要はありません。

txn.addAnalyticsData(key, value)

• key: 追加される分析データのキー
• value: このキーに追加される値

このトランザクション用に生成された分析にカスタムデータを添付します。アプリケーションにトランザクションハンドルがある場合は、txn.addAnalyticsData(key, value) を呼び出すことができます。そうでない場合は、appd.addAnalyticsData(key, value) を使用します。 

この機能を有効にするには、require ステートメントの分析設定を設定する必要があります。詳細については、Node.js設定参考資料を参照してください。Analytics の詳細については、「分析データソース」を参照してください。

txn.onResponseComplete(req, res)

• req：トランザクションの HTTP 要求
• res：トランザクションの HTTP 応答

関連付けられた HTTP 応答が完了したときに通知されるトランザクションに設定できるコールバックメソッド。txn.addAnalyticsData(key, value) で使用して、トランザクションが完了する前に、txn.onResponseComplete(req, res) が完了したら応答のデータを追加できます。コールバック関数が使用できる場合、エージェントはトランザクションを終了する前に、HTTP 応答が完了した直後にこの API を呼び出します。呼び出し関数を定義し、それをコールバックに割り当てる必要があります。

mytxn.onResponseComplete = function customTitle (req, res) {
    // get status code of HTTP response
    code = res.statusCode;
    txn.addAnalyticsData ("http response code", code);
};

終了コールの管理

exitCall.addAnalyticsData（キー、値）

• key: 追加される分析データのキー
• value: このキーに追加される値

このトランザクション用に生成された既存の分析データを終了コールに付加します。 

このトランザクション用に生成された分析にカスタムデータを添付します。アプリケーションにトランザクションハンドルがある場合は、txn.addAnalyticsData(key, value) を呼び出すことができます。そうでない場合は、appd.addAnalyticsData(key, value) を使用します。 

この機能を有効にするには、require ステートメントの分析設定を設定する必要があります。詳細については、Node.js設定参考資料を参照してください。

TimePromise.prototype.startExitCall(exitCallInfo)

• exitCallInfo オブジェクト

exitCallInfo オブジェクトには次の必須プロパティがあります。

• • exitType：文字列。終了コールのタイプ。「EXIT_HTTP」、「EXIT_DB」、「EXIT_CACHE」、「EXIT_RABBITMQ」、「EXIT_WEBSERVICE」のいずれか
  • label：文字列。AppDynamics UI における終了コールのラベル
  • backendName：文字列。バックエンド リモート システムまたはサービスの名前
  • identifyingProperties：オブジェクト。呼び出されるリモートシステムまたはサービスを独自に識別する名前/値ペアのハッシュ。「Backend Identifying Properties」を参照してください。

exitCallInfo オブジェクトが記述するカスタム終了コールを作成し開始します。

必須プロパティに加え、追加の識別プロパティを提供することができます。

ExitCall を返します。「Exit Call Properties」を参照してください。

{ 
  exitType: “EXIT_DB”,
  label: "New SQL",
  backendName: "NewDB"
  identifyingProperties: {
    “HOST”: “database-server”, 
    “PORT”: “12345”, 
    “DATABASE”: “my-database”, 
    "VENDOR" = “MYSQL"
  },
  …etc...
}

TimePromise.prototype.endExitCall(exitCall, error)

• exitCall：startExitCall() によって返される ExitCall インスタンス
• error: any; optional

カスタム終了コールを終了し、このトランザクションに添付します。

error が渡されると、エラーが終了コールに関連付けられ、終了コールがエラー状態であるというフラグが立てられます。

TimePromise.prototype.beforeExitCall(exitCall)

• exitCall: ExitCall

ExitCall を返します。

自動検出された（カスタムでない）終了コールを変更するためのオプションのコールバック。  

コールバック関数が使用できる場合、アプリケーションが終了コールを行う直前に、エージェントはこの API を呼び出します。コールバックを使用して以下を行うことができます。

• コントローラに報告された終了コールの変更。
• 何も返さず、終了コールのすべての報告を抑制。 
• ダウンストリームトランザクションの相関情報を作成するために終了コールを取得。

以下は、コントローラに報告される終了コールの変更の例です。

txn.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;
}

TimePromise.prototype.exitCallCompleted(exitCall)

    •    exitCall：ExitCall

（省略可）ExitCallを返します。startExitCall() により作成されたカスタム終了コール、または終了コール完了時に自動検出された終了コールの変更のためのコールバック。

コールバック関数を指定すると、エージェントは終了コールが完了した直後にこのAPIを呼び出します。

exitCallCompleted() を使用して、変更された終了コールを返すことにより終了コールがコントローラに報告される方法を変更します。このコールバックを使用してバックエンド識別プロパティを変更しないでください。 

以下のコードは、コントローラに報告される終了コールの変更の例です。

txn.exitCallCompleted = function customExitCallPostProcessor(exitCall) {
    // report MongoDB read and write operations as distinct exit calls
    if (exitCall.backendName === "MongoDB")
        exitCall.label += " " + exitCall.category;
}

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

appd.parseCorrelationInfo(source)

• source: 文字列または HttpRequest

相関するアップストリーム トランザクションについて記述します。HttpRequest オブジェクトが渡される際には、トランザクション相関ヘッダーが添付されている必要があります。

成功すると、startTransaction() が使用できる CorrelationHeader オブジェクトを返し、source で記述されるアップストリーム トランザクションと相関するトランザクションを作成します。source を解析できない場合は false を返します。これが起こるのは、ソースが相関ヘッダーが添付されていないHTTP要求であるか、文字列パラメータが相関ヘッダーとして認識されない場合です。

標準 http.request() API を使用して作成された HTTP 要求には、相関情報が自動的に追加されます。受信した要求を source として渡すことにより、別の Node.js プロセスからの HTTP 要求に応じて作成されたカスタムトランザクションを相互に関連付けることができます。

他の終了コールタイプの場合は、相関情報が元のトランザクションにどのように添付され、ダウンストリームトランザクションで抽出されるかを定義する必要があります。 

TimePromise.prototype.createCorrelationInfo(exitCall, doNotResolve)

• exitCall: ExitCall
• doNotResolve: オプション、true|false


入力 exitCall は、次のいずれかになります。

• カスタム終了コールの場合は、startExitCall() が返す値
• 自動検出の終了コールの場合は、beforeExitCall() コールバックに入力するパラメータ

バックエンドをティアに転換したくない場合は、doNotResolve パラメータを true に設定します。デフォルトではfalseであり、つまりバックエンドは呼び出し側のティアに転換されます。メッセージキューなど、サービスの受け取り側と提供側の間に1:1の関係がないサービスへの終了コールなどにこの値を設定するのが良いでしょう。詳細については、「リモートサービスのティアへの転換」を参照してください。

ダウンストリームトランザクションがこのトランザクションとの相関に使用できる文字列エンコード相関ヘッダーを返します。

終了コールのプロパティ

この表では、検出された各終了コールタイプの、終了コールオブジェクトのプロパティについて説明します。

表内のダッシュ（–）は、検出された終了コールにプロパティが存在するものの、形式が指定されていないことを示します。これにより、カスタム終了呼び出しを作成するときに独自の値を設定できます。

「該当なし」とは、その終了コールタイプでプロパティが使用されていないことを示します。検出された終了コールには、ここに記載されていない追加のプロパティがある可能性があります。

^* ホスト、ポート、およびパス。クエリ文字列は含まれません

バックエンドを識別するプロパティ

この表は、Node.jsエージェントが自動検出するバックエンドの識別プロパティを一覧にしています。

これらのプロパティは、コントローラ UI でバックエンドダッシュボードの右上パネルに表示されます。

¹ <ホスト>:<ポート> 形式の「\n」で区切られたサーバアドレスの一覧
² <ホスト>:<ポート> 形式の単一サーバアドレス