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' のようになります。オプションの onError コールバックは、 onRequire パラメータがエラーになった場合に呼び出されます。これは、インストゥルメンテーションのデバッグに役立ちます。

この方法を使って

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

詳しくは、New Relic の Node.js instrumentation tutorial on Github をご覧ください。

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

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

このメソッドは、 newrelic.instrument() と同じですが、 データストアに特化したシム を提供する点が異なります。詳細は、New Relic's Node.js datastore instrumentation tutorial on Github をご覧ください。

newrelic.instrumentLoadedModule(moduleName, moduleInstance)

instrumentLoadedModule メソッドを使うと、 require('newrelic'); をアプリのメインモジュールの1行目にすることができないような状況で、ストックのインストルメントを特定のモジュールに追加することができます。

// 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])

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

このメソッドは、 newrelic.instrument() と同じですが、 メッセージサービスに特化したシム を提供する点が異なります。詳細は、New Relic's Node.js message service instrumentation tutorial on Github をご覧ください。

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

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

このメソッドは、 newrelic.instrument() と同じですが、 Web フレームワークに特化したシムを提供している点が異なります 。詳しくは、New Relic's Node.js web framework instrumentation tutorial on Github をご覧ください。

newrelic.startWebTransaction(url, handle)

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

• url は、トランザクション名を定義するもので、静的なものである必要があります。ユーザーIDなどの可変データは含めないでください。
• ハンドル には、インストルメント化したい機能が定義されています。

New Relic は、自動インスツルメンテーションで取得されるすべてのメトリクスを取得します。また、 startSegment() による手動のインスツルメンテーションも行います。

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

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

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

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

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

New Relic は、自動インスツルメンテーションで取得されるすべてのメトリクスを取得します。また、 startSegment() による手動のインスツルメンテーションも行います。

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

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

newrelic.getTransaction()

現在実行中のトランザクションのハンドルを返します。このハンドルは、どのようなコンテキストであっても、与えられたトランザクションを安全に操作するために使用することができます。 newrelic.startWebTransaction() や newrelic.startBackgroundTransaction() と一緒に使うとよいでしょう。

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

newrelic.endTransaction()

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

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

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

• 名前 は、セグメントの名前を定義します。この名前は、トランザクションのトレースに表示されるほか、New Relic UI の新しいメトリックとして表示されます。
• record フラグは、セグメントをメトリックとして記録するかどうかを定義します。
• ハンドラー は、セグメントとしてトラッキングしたい機能です。
• オプションの コールバック は、ハンドラーが作業を終えた後に発火するように渡される関数です。

エージェントは、 startSegment が呼び出されたときに、セグメントの計時を開始します。セグメントは、 ハンドラ が実行を終了したとき、または コールバック が提供されている場合はそれが実行されたときに終了します。

newrelic.recordMetric(name, value)

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

• 値 が数値の場合、イベントに関連する測定値の大きさを表す必要があります。例えば、特定のメソッドコールの継続時間などです。
• value がオブジェクトの場合、 count, total, min, max, sumOfSquares のキーが含まれていなければならず、すべて数字の値を持ちます。このフォームは、独自にメトリクスを集計し、定期的に報告するのに便利です。例えば、 setInterval からの報告です。これらの値は、同じメトリクスに対して以前に収集された値と一緒に集約されます。これらのキーの名前は、プラットフォームAPIで使用されているキーの名前と一致しています。

newrelic.incrementMetric(name, [amount])

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

newrelic.recordCustomEvent(eventType, attributes)

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

• eventType は、255文字以下の英数字の文字列でなければなりません。
• 属性 は、キーと値のペアのオブジェクトでなければなりません。キーは255文字以下で、値は文字列、数値、またはブール値でなければなりません。

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

newrelic.recordCustomEvent('MessagingEvent', attributes);

transactionHandle.end([callback])

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

コールバック は、トランザクションが完全に終了したときに呼び出されます。終了したトランザクションは、第一引数としてコールバックに渡されます。

transactionHandle.ignore()

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

transactionHandle.insertDistributedTraceHeaders(headers)

このコールとそのパートナーコール acceptDistributedTraceHeaders の使用方法については、まず Enable distributed tracing with Agent APIs をお読みください。

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

// 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 の使用方法については、まず Enable distributed tracing with Agent APIs をお読みください。

transactionHandle.acceptDistributedTraceHeaders は、分散トレースに含めるために呼び出されたサービスをインスツルメントするために使用されます。 insertDistributedTraceHeaders または他の W3C Trace Context 準拠のトレーサーによって生成されたペイロードを受け入れることで、トレース内のスパンをリンクします。このメソッドは、受信したリクエストのヘッダーを受け入れ、W3C Trace Context ヘッダーを探し、見つからない場合は 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 、 Enable distributed tracing with Agent APIs を参照してください。

このコールは、分散型トレーシングの実装に使用されます。ペイロードを生成し、受信側のアプリケーションが 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 の使用方法については、まず Enable distributed tracing with Agent APIs をお読みください。

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

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.setIgnoreTransaction(ignored)

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

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

newrelic.noticeError(error, [customAttributes])

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

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

newrelic.shutdown([options], callback)

エージェントを優雅にシャットダウンするには、この方法を使用します。

例:

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

newrelic.getLinkingMetadata()

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

意味のある値を持つアイテムのみが含まれます。例えば、分散型トレーシングが無効の場合、 trace.id は含まれません。

newrelic.getTraceMetadata()

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

{pattern :"pattern", name :"name"} という形式のルールのリストです。 受信したリクエストの URL を pattern にマッチングさせ、マッチングした New Relic トランザクションの name に名前を付けるためのものです。これは正規表現による置換のようなもので、パターンは文字列、または JavaScript の正規表現リテラルとして設定でき、pattern と name の両方が必須となります。

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

これは、環境変数 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プロセスが再起動されるまで削除できません。また、Node.jsエージェントの設定で追加することもできます。両方のパラメータが必要です。

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