Node.jsエージェントAPI

newrelic.setTransactionName(name)

リクエストの命名要件 に従って、現在のリクエストに名前を付けます。この関数は、HTTP リクエストハンドラーのコンテキスト内であれば、リクエストの処理が開始された後、リクエストが終了する前であれば、いつでも呼び出すことができます。一般的には、リクエストとレスポンスのオブジェクトがスコープ内にあれば、名前を設定することができます。

newrelic.setTransactionName()を明示的に呼び出すと、Express または Restify ルートによって設定された名前が上書きされます。また、 newrelic.setTransactionName()とnewrelic.setControllerName()を呼び出すと、互いに上書きされます。リクエストが終了する前に最後に実行されたものが優先されます。

newrelic.setControllerName(name, [action])

オプションで現在のコントローラー アクションを含む、コントローラー スタイルのパターンを使用して現在のリクエストに名前を付けます。アクションが省略された場合、New Relic は HTTP メソッド (GET、POST など) をアクションとして含めます。newrelic.setControllerName()を呼び出すことができる場合のルールは、リクエストの命名要件を含め、 newrelic.setTransactionName()の場合と同じです。

newrelic.setControllerName()を明示的に呼び出すと、Express または Restify ルートによって設定された名前が上書きされます。また、 newrelic.setTransactionName()とnewrelic.setControllerName()を呼び出すと、互いに上書きされます。リクエストが終了する前に最後に実行されたものが優先されます。

newrelic.instrument(moduleName, onRequire [, onError])

特定のモジュールにインスツルメンテーション・コールバックを設定します。

提供されたonRequireコールバックは、指定されたモジュールがrequireでロードされるときに発生します。moduleNameパラメータは、 requireに渡される文字列である必要があります。たとえば、 'express'または'amqplib/callback_api' 。onRequireパラメータがエラーをスローした場合、オプションのonErrorコールバックが呼び出されます。これは、インストルメンテーションのデバッグに役立ちます。

この方法を使って

• 現在New Relicで計測されていないモジュールに計測機能を追加します。
• 自分のコードをインストゥルメント化する。
• Node.jsエージェントに内蔵されているインスツルメンテーションを独自のものに置き換えます。

詳細については、Github の New Relic の Node.js インストルメンテーション チュートリアルを参照してください。

newrelic.instrumentDatastore(moduleName, onRequire [, onError])

データストア・モジュールのインストルメンテーション・コールバックを設定します。

このメソッドはnewrelic.instrument()と同じですが、データストアに特化した shimを提供する点が異なります。詳細については、Github の New Relic の Node.js データストア インストルメンテーション チュートリアルを参照してください。

newrelic.instrumentLoadedModule(moduleName, moduleInstance)

instrumentLoadedModuleメソッドを使用すると、アプリのメイン モジュールの最初の行としてrequire('newrelic');を使用できない状況で、ストック インストルメンテーションを特定のモジュールに追加できます。

// load the agent
const newrelic = require('newrelic');

// module loaded before newrelic
const expressModule = require('express');

// instrument express after the agent has been loaded
newrelic.instrumentLoadedModule(
  'express',    // the module's name, as a string
  expressModule // the module instance
);

newrelic.instrumentMessages(moduleName, onRequire [, onError])

メッセージサービスクライアントモジュールのインスツルメンテーションコールバックを設定します。

このメソッドは、メッセージ サービスに特化した shim を提供することを除いて、 newrelic.instrument()と同じです。詳細については、Github の New Relic の Node.js メッセージ サービス インストルメンテーション チュートリアルを参照してください。

newrelic.instrumentWebframework(moduleName, onRequire [, onError])

Webフレームワークモジュールのインスツルメンテーションコールバックを設定します。

このメソッドは、ウェブ フレームワークに特化した shim を提供することを除いて、 newrelic.instrument()と同じです。詳細については、Github の New Relic の Node.js Web フレームワーク インストルメンテーション チュートリアルを参照してください。

newrelic.startWebTransaction(url, handle)

指定されたウェブトランザクションをインストゥルメントします。この API コールを使用すると、New Relic が自動的に検出しないトランザクションをインストゥルメントすることができます 。

• urlはトランザクション名を定義し、静的である必要があります。ユーザー ID などの可変データを含めないでください。
• handleは、計測する関数を定義します。

New Relic は、自動インストルメンテーションとstartSegment()を介した手動インストルメンテーションによってキャプチャされるすべてのメトリクスをキャプチャします。

カスタム トランザクションは、トランザクションの開始時にnewrelic.getTransaction()を呼び出して手動で処理し、終了時にtransaction.end()を呼び出す必要があります。New Relic は、 newrelic.startWebTransaction()が呼び出されるとトランザクションのタイミングを開始し、 transaction.end()が呼び出されるとトランザクションを終了します。

トランザクションの終了を示す promise を返すこともできます。この約束が拒否された場合、New Relic のエラー追跡に自動的にフックされないことに注意してください。これはnoticeError()で手動で行う必要があります。

newrelic.startBackgroundTransaction(name, [group], handle)

指定されたバックグラウンドトランザクションをインストゥルメントします。この API コールを使用すると、New Relic のインスツルメンテーションを拡張して、 バックグラウンド トランザクションからデータをキャプチャすることができます 。

• nameはトランザクション名を定義し、静的である必要があります。ユーザー ID などの可変データを含めないでください。
• groupはオプションであり、ユーザー インターフェースのトランザクション タイプを介して類似のジョブをグループ化できます。nameと同様に、 groupは静的である必要があります。
• handleは、計測するバックグラウンド ジョブ全体を含む関数を定義します。

New Relic は、自動インストルメンテーションとstartSegment()を介した手動インストルメンテーションによってキャプチャされるすべてのメトリクスをキャプチャします。

カスタム トランザクションは、トランザクションの開始時にnewrelic.getTransaction()を呼び出して手動で処理し、終了時にtransaction.end()を呼び出す必要があります。New Relic は、 newrelic.startBackgroundTransaction()が呼び出されるとトランザクションのタイミングを開始し、 transaction.end()が呼び出されるとトランザクションを終了します。

トランザクションの終了を示す promise を返すこともできます。この約束が拒否された場合、New Relic のエラー追跡に自動的にフックされないことに注意してください。これはnoticeError()で手動で行う必要があります。

newrelic.getTransaction()

現在実行中のトランザクションのハンドルを返します。このハンドルを使用して、任意のコンテキストから安全に特定のトランザクションと対話できます。newrelic.startWebTransaction()およびnewrelic.startBackgroundTransaction()と一緒に使用するのが最適です。

詳しくは、「トランザクション・ハンドル」の項を参照してください。

newrelic.endTransaction()

現在の web または background カスタムトランザクションを終了します。このメソッドを呼び出すには、正しいトランザクション・コンテキストにいることが必要です。このAPIコールは引数を取りません。

newrelic.startSegment(name, record, handler, callback)

特定のメソッドをインストゥルメント化して、 トランザクションの可視性を向上させる 、またはオプションでメトリックに変換することができます。

• nameは、セグメントの名前を定義します。この名前は、トランザクション追跡に表示され、New Relic UI の新しいメトリックとして表示されます。
• recordフラグは、セグメントを指標として記録するかどうかを定義します。
• handlerは、セグメントとして追跡する関数です。
• オプションのcallbackは、処理が完了した後に起動するハンドラに渡される関数です。

エージェントは、セグメントが呼び出されると、セグメントのタイミング startSegment 開始します。 セグメントは、 handler が実行を終了するか、または callback が提供されている場合は起動されたときに終了します。

newrelic.recordMetric(name, value)

recordMetricを使用して、通常は特定の期間に関連付けられたイベント ベースの指標を記録します。nameは、標準のメトリック命名規則に従った文字列でなければなりません。valueは通常は数値ですが、オブジェクトにすることもできます。

• valueが数値の場合、イベントに関連する測定値の大きさを表す必要があります。たとえば、特定のメソッド呼び出しの期間です。
• valueがオブジェクトの場合、 count 、 total 、 min 、 max 、およびsumOfSquaresキーをすべて数値で含む必要があります。このフォームは、メトリックを独自に集計し、定期的にレポートするのに役立ちます。たとえば、 setIntervalから。これらの値は、同じメトリックに対して以前に収集された値と集計されます。これらのキーの名前は、プラットフォーム API で使用されるキーの名前と一致します。

newrelic.incrementMetric(name, [amount])

incrementMetricを使用して、単純なカウンターとして機能するメトリックを更新します。選択したメトリックのカウントは、指定された量だけ増加し、デフォルトは 1 です。

newrelic.recordCustomEvent(eventType, attributes)

recordCustomEventを使用して、通常は特定の期間に関連付けられたイベント ベースの指標を記録します。

• eventTypeは、255 文字未満の英数字の文字列でなければなりません。
• attributesは、キーと値のペアのオブジェクトでなければなりません。キーは 255 文字未満である必要があり、値は文字列、数値、またはブール値である必要があります。

const attributes = {
  attribute1: 'value1',
  attribute2: 2
};

newrelic.recordCustomEvent('MessagingEvent', attributes);

newrelic.recordLogEvent({message, level})

ロギング フレームワークに対して自動ロギング インストルメンテーションが不十分な場合は、 recordLogEventを使用してログ イベントを記録します。受け入れられるパラメータ タイプの詳細については、自動生成されたドキュメントを参照してください。

const error = new SystemError('invalid state');
const timestamp = Date.now();

newrelic.recordLogEvent({message: 'an error happened', level: 'error', timestamp, error});

transactionHandle.end([callback])

transactionHandle.endを使用して、ハンドル インスタンスによって参照されるトランザクションを終了します。

トランザクションが完全に終了すると、 callbackが呼び出されます。最初の引数としてコールバックに渡された終了したトランザクション。

transactionHandle.ignore()

ハンドル インスタンスによって参照されるトランザクションを無視するには、 transactionHandle.ignoreを使用します。

transactionHandle.insertDistributedTraceHeaders(headers)

この呼び出しとそのパートナー呼び出しacceptDistributedTraceHeadersの使用方法に関するコンテキストについては、まずエージェント API で分散トレースを有効にする をお読みください。

transactionHandle.insertDistributedTraceHeaders 分散トレースの実装に使用されます。W3C Trace Context ヘッダーと New Relic Distributed Trace ヘッダーを追加することで、渡されたheadersマップを変更します。New Relic ヘッダーは、構成でdistributed_tracing.exclude_newrelic_header: trueを使用して無効にすることができます。このメソッドは、New Relic Distributed Trace ペイロードのみを作成する非推奨のcreateDistributedTracePayloadメソッドを置き換えます。

// Call newrelic.getTransaction to retrieve a handle on the current transaction.
const transactionHandle = newrelic.getTransaction();

// This could be a header object from an incoming request as well
const headersObject = {};
newrelic.startBackgroundTransaction('background task', function executeTransaction() {
  const transaction = newrelic.getTransaction();
  // generate the headers
  transaction.insertDistributedTraceHeaders(headersObject);
});

transactionHandle.acceptDistributedTraceHeaders(transportType, headers)

この呼び出しとそのパートナー呼び出しinsertDistributedTraceHeadersの使用方法に関するコンテキストについては、まずエージェント API で分散トレースを有効にする をお読みください。

transactionHandle.acceptDistributedTraceHeaders 分散トレースに含めるために呼び出されたサービスを計測するために使用されます。insertDistributedTraceHeadersによって生成されたペイロード、または他の W3C トレース コンテキスト準拠のトレーサによって生成されたペイロードを受け入れることで、トレース内のスパンをリンクします。このメソッドは、着信リクエストのヘッダーを受け入れ、W3C トレース コンテキスト ヘッダーを探し、見つからない場合は、New Relic 分散トレース ヘッダーにフォールバックします。このメソッドは非推奨 (現在はバージョン 7.0.0 で削除されています) を置き換えます。acceptDistributedTracePayloadメソッド。New Relic の分散トレース ペイロードのみを処理します。

transportType 次の文字列のいずれかである必要があります。

• AMQP
• HTTP
• HTTPS
• IronMQ
• JMS
• カフカ
• その他
• キュー
• 不明

headers 着信リクエストのすべてのヘッダーを含むオブジェクトである必要があります。キーは小文字でなければなりません。

// incoming Kafka message headers
const headersObject = message.headers;

// Call newrelic.getTransaction to retrieve a handle on the current transaction.
const transactionHandle = newrelic.getTransaction();

newrelic.startBackgroundTransaction('background task', function executeTransaction() {
  const transaction = newrelic.getTransaction();

  // accept the headers
  transaction.acceptDistributedTraceHeaders('Kafka', headersObject);
});

transactionHandle.createDistributedTracePayload()

この呼び出しとそのパートナー呼び出しacceptDistributedTracePayloadを使用する方法については、エージェント API で分散トレースを有効にする を参照してください。

この呼び出しは、分散トレースを実装するために使用されます。acceptDistributedTracePayloadを使用して受信アプリケーションによって読み取られるペイロードを生成します。

DistributedTracePayloadオブジェクトには、異なる形式でペイロードを生成するために使用できる 2 つのメソッドがあります。

• DistributedTracePayload#text: ペイロードの JSON 表現を返します。

  ネストされたバックグラウンド・トランザクションのリンク

  // Call newrelic.getTransaction to retrieve a handle on the current transaction.
  var transactionHandle = newrelic.getTransaction();
  var payload = transactionHandle.createDistributedTracePayload();
  var jsonPayload = payload.text();
  newrelic.startBackgroundTransaction('background task', function executeTransaction() {
    var backgroundHandle = newrelic.getTransaction();
    // Link the nested transaction by accepting the payload with the background transaction's handle
    backgroundHandle.acceptDistributedTracePayload(jsonPayload);
  });

  コピー

• DistributedTracePayload#httpSafe: ペイロードの base64 でエンコードされた JSON 表現を返します。

  発信するリクエストにペイロードを置く

  // Call newrelic.getTransaction to retrieve a handle on the current transaction.
  var transactionHandle = newrelic.getTransaction();
  var payload = transactionHandle.createDistributedTracePayload();
  // Place the base64 encoded value on an outbound request header.
  req.headers[myTracingHeader] = payload.httpSafe();

  コピー

transactionHandle.acceptDistributedTracePayload(payload)

この呼び出しとそのパートナー呼び出しcreateDistributedTracePayloadの使用方法に関するコンテキストについては、まずエージェント API で分散トレースを有効にする をお読みください。

transactionHandle.acceptDistributedTracePayload 分散トレースに含めるために呼び出されたサービスを計測するために使用されます。createDistributedTracePayloadによって生成されたペイロードを受け入れることで、トレース内のスパンをリンクします。

transactionHandle.isSampled()

このトレースがサンプリングされているかどうかを返します。

newrelic.addCustomAttribute(name, value)

New Relic UI でトランザクションのトレースとともに表示するカスタム属性値を設定します。これは、カスタム属性を設定する場所があるように、トランザクションのコンテキスト内で呼び出す必要があります。カスタム属性は、APM のトランザクショントレースの詳細ビューと、トランザクションのエラーに表示されます。

newrelic.addCustomAttribute('attribute1', 'value1')

newrelic.addCustomAttributes(attributes)

New Relic UI でトランザクショントレースとともに表示される複数のカスタム属性値を設定します。属性は 1 つのオブジェクトとして渡す必要があります。これは、カスタム属性を設定する場所があるように、トランザクションのコンテキスト内で呼び出す必要があります。カスタム属性は、トランザクショントレースの詳細ビューとトランザクションのエラーに表示されます。

const attributes = {
  attribute1: 'value1',
  attribute2: 2
};

newrelic.addCustomAttributes(attributes);

newrelic.addCustomSpanAttribute(name, value)

New Relic UI でトランザクション トレース スパンと共に表示されるカスタム スパン属性値を設定します。これは、カスタム スパン属性を設定する場所があるように、アクティブなセグメント/スパンのコンテキスト内で呼び出す必要があります。カスタム スパン属性は、スパン詳細ビューの Attributes セクションに表示されます。

newrelic.addCustomSpanAttribute('attribute1', 'value')

newrelic.addCustomSpanAttributes(attributes)

New Relic UI でトランザクション トレース スパンとともに表示される複数のカスタム スパン属性値を設定します。属性は 1 つのオブジェクトとして渡す必要があります。カスタム スパン アトリビュートを設定する場所を確保するため、これはアクティブなセグメント/スパンのコンテキスト内で呼び出す必要があります。カスタム スパン アトリビュートは、スパン詳細ビューの Attributes セクションに表示されます。

const attributes = {
  attribute1: 'value1',
  attribute2: 'value2'
};

newrelic.addCustomSpanAttributes(attributes);

newrelic.getBrowserTimingHeader()

ブラウザモニタリング を有効にするために、HTML ページのヘッダに挿入する HTML スニペットを返します。このHTMLは、小さなJavaScriptファイルを取得し、ページタイマーを開始するようにブラウザに指示します。

newrelic.noticeError(error, [customAttributes], [expected])

アプリがドメインやtry/catch句を使って独自のエラー処理を行っているが、アプリから出たエラーの数に関するすべての情報を一元管理したい場合に、このコールを使用します。他のNode.jsのコールとは異なり、このコールはルート・ハンドラの外で使用することができますが、トランザクション・スコープ内からコールされた場合は、追加のコンテキストを持つことになります。

error Errorまたはそのサブタイプの 1 つである必要がありますが、API は.messageまたは.stackプロパティが添付された文字列とオブジェクトを処理します。

customAttributes New Relic UI に表示される任意のカスタム属性のオプション オブジェクトです。

expected エラーを予想されるエラーとして分類するためのオプションのブール値です。noticeErrorで収集されたエラーがexpectedである場合、それは収集されて報告されますが、 Apdexまたはエラー率メトリックには影響しません。デフォルトでは、 expectedはfalseです。

例：

try {
  performSomeTask();
} catch(err) {
  newrelic.noticeError(
    err,
    { extraInformation: "error already handled in the application" },
    true
  );
}

newrelic.setErrorGroupCallback(callback)

このメソッドを使用すると、カスタム コールバックを定義してエラー グループ名を生成できます。この名前は、 error.group.name エージェント属性を介して同様のエラーをグループ化するためにエラー インボックスで使用されます。

指定された関数は文字列を返し、オブジェクトを引数として受け取る必要があります。オブジェクトには、発生したエラーに関連する情報が含まれており、次の形式になっています。

{
  "customAttributes": object,
  "request.uri": string,
  "http.statusCode": string,
  "http.method": string,
  "error": Error,
  "error.expected": boolean
}

この関数を複数回呼び出すと、このコールバック関数の以前に定義されたバージョンが置き換えられます。

この機能の詳細については、 サンプル アプリを参照してください。

newrelic.setIgnoreTransaction(ignored)

与えられたリクエストを無視するかどうかをモジュールに伝えます。これにより、長いポーリングのある無関係なルートや、時間のかかることがわかっているリクエストを明示的にフィルタリングすることができます。また、他の方法では無視されてしまうリクエストのメトリクスを収集することもできます。

• トランザクションを無視するには、パラメーターを trueに設定します。これにより、トランザクションが無視されます。
• この関数でトランザクションが無視されないようにするには、パラメーターfalseを渡します。
• nullまたはundefinedを渡しても、トランザクションが無視されるかどうかは変わりません。

newrelic.setUserID(string)

このメソッドを使用すると、一意の識別子をトランザクション イベント、トランザクション追跡、およびトランザクション内のエラーに関連付けることができます。新しいプロパティ enduser.idがエラーに追加され、エラー インボックスに報告されます。

newrelic.shutdown(options, callback)

このメソッドを使用して、エージェントを正常にシャットダウンします。両方のパラメーターはオプションです。パラメータを示す概要表を次に示します。

以下は、オブジェクトのシャットダウン オプションを示す詳細表です。

例：

newrelic.shutdown({collectPendingData: true, timeout: 10000}, (error) => {
  process.exit();
});

newrelic.getLinkingMetadata()

トレースやエンティティのリンクに使用できるキー／バリューペアを返します。

意味のある値を持つアイテムのみが含まれます。たとえば、分散トレースが無効になっている場合、 trace.idは含まれません。

newrelic.getTraceMetadata()

現在のトレースIDとスパンIDを含むオブジェクトを返します。

着信リクエスト URL をpatternに一致させ、一致する New Relic トランザクションのnameに名前を付けるための、形式{pattern : "pattern", name : "name"}のルールのリスト。これは正規表現の置換として機能し、パターンを文字列または JavaScript 正規表現リテラルとして設定でき、パターンと名前の両方が必要です。

正規表現を文字列として渡す場合は、バックスラッシュをエスケープしてください。エージェントは、パターン内の文字列として渡された場合、バックスラッシュを保持しません。パターンは順番に評価され、その性質上、最終的なものであるため、最も具体的なものから最も一般的なものまで、設定ルールを定義してください。詳細については、 命名ガイドライン を参照してください。

これは、環境変数NEW_RELIC_NAMING_RULESを使用して設定することもできます。複数のルールがコンマ区切りの JSON オブジェクト リテラルのリストとして渡されます。

NEW_RELIC_NAMING_RULES='{"pattern":"^t","name":"u"},{"pattern":"^u","name":"t"}'

オプションのルール属性

追加のオプション属性があります。

pattern: '[0-9]+',
replace_all: true

ネーミングルールのテスト

Node.jsエージェントには、ネーミングルールをテストするためのコマンドラインツールが付属しています。詳しくは、アプリがインストールされているディレクトリのターミナル・ウィンドウで以下のコマンドを実行してください。

$
node node_modules/.bin/newrelic-naming-rules

ネーミングルールの例 [#examples-rules]

ネーミングルールとその結果の例をご紹介します。

pattern: "^/items/[0-9]+$",
name: "/items/:id"

/items/123   =>  /items/:id
/orders/123  =>  /orders/123   (not replaced since the rule is a full match)

pattern: "[0-9]+",
name: ":id"

/orders/123            =>  /orders/:id
/items/123             =>  /items/:id
/orders/123/items/123  =>  /orders/:id/items/123

pattern: "[0-9]+",
name: ":id",
replace_all: true

/orders/123/items/123  =>  /orders/:id/items/:id

pattern: '^/(items|orders)/[0-9]+$',
name: '/\\1/:id'

/orders/123  =>  /orders/:id
/items/123   =>  /items/:id

これは、環境変数NEW_RELIC_IGNORING_RULESを介して設定することもでき、コンマ区切りのパターンのリストとして複数のルールが渡されます。現在、パターン内のコンマをエスケープする方法はありません。

NEW_RELIC_IGNORING_RULES='^/socket\.io/\*/xhr-polling,ignore_me'

socket.io を使用している場合は、すぐにルールを無視するユースケースがあります。socket.io の long-polling がレスポンスタイムのメトリクスを支配し、アプリケーションの Apdex メトリクスに影響を与えないようにするには、次のようなルールを追加します。

// newrelic.js
exports.config = {
  // other configuration
  rules : {
    ignore : [
      '^\/socket\.io\/.*\/xhr-polling'
    ]
  }
};

rules.nameのプログラム バージョン。命名規則が追加されると、Node.js プロセスが再起動されるまで削除できません。また、Node.js エージェントの構成を介して追加することもできます。両方のパラメータが必要です。

rules.ignoreのプログラム版。無視ルールが追加されると、Node.js プロセスが再起動されるまで削除できません。また、Node.js エージェントの構成を介して追加することもできます。このパラメーターは必須です。