New Relic は、Node.js アプリケーションに関する有用なメトリクスを提供するために必要な情報を取得するためのツールをいくつか提供しています。これらには次のようなものがあります。
- ExpressとRestifyのルーターからルート名(使用されている場合)を読み込む
- APIを使用して、現在のリクエストに名前を付ける。単純な名前や、アクションを持つコントローラのグループを使用する。
- リクエストの生のURLに対してマッチした正規表現に基づいて、リクエストをリネームまたは無視するようマークすることができる、エージェントの設定に保存されたルールをサポート(APIコールとしても利用可能)
New Relic が追跡する名前の数は、ユーザー・エクスペリエンスが堅牢であるように十分小さくする必要があります。また、アプリケーションの問題点をより簡単に特定できるように、(データに圧倒されることなく)適切な量の情報を提供するのに十分な規模である必要があります。
詳細については、Github のNode.js エージェント構成ドキュメントとNode.js エージェント API ドキュメントを参照してください。
リクエスト名
Node.js エージェントは、潜在的にパラメーター化されたパス ( /user/:id
など) または正規表現 ( /^/user/([-0-9a-f]+)$/
など) とともに HTTP メソッドをキャプチャします。これらの情報は、リクエスト名の一部になります。
低速トランザクション トレースをサポートしていて、構成ファイルのattributes.include
に'request.parameters.*'
を追加している場合、トランザクション トレースにもリクエストのパラメータとその値が添付されます。Node.js エージェントが使用する要求名が気に入らない場合は、API 呼び出しを使用して、よりわかりやすい名前を作成できます。
ヒント
汎用名でリクエストをグループ化する場合は、 /*
で十分であり、構成ファイルや API 呼び出しをカスタマイズする必要はありません。
要件
New Relic では、多くのチャートやテーブルでリクエストをグループ化するためにリクエスト名を使用しています。異なるリクエスト名の数が増えると、これらのビジュアライゼーションの価値は下がります。
例えば、作成するリクエスト名にGUID、数値ID、タイムスタンプのような潜在的に動的なデータを含まないようにします。リクエストがトランザクショントレースを生成するほど遅い場合、そのトレースにはオリジナルのURLが含まれます。パラメータキャプチャを有効にした場合、パラメータもトレースに添付されます。
ヒント
50種類以上のトランザクション名を持たないようにしてください。例えば、リクエスト名が数百種類以上ある場合は、ネーミング戦略を見直してください。
メトリクスのグループ化問題を回避する
"" New Relic では、このような問題に対処するためにいくつかの方法を用意しています。最も厳しい方法は、問題のあるアプリケーションを拒否リストに追加することです。
これらのリクエスト名付けツールの使用に注意する主な理由は、アプリケーションにこのような事態が発生するのを防ぐためです。詳細については、 Metric grouping issues をご覧ください。
ガイドライン
設定ルールは、最も具体的なものから最も一般的なものまで定義してください。設定ファイルに記載された最初のルール、または Node.js transaction naming API で追加されたルールが最初に適用されるため、対象を絞る必要があります。より一般的な"fall-through" のルールは、リストの最後の方に追加してください。なぜなら、これらのルールは、Node.js トランザクション ネーミング API を使用して設定または追加された順に評価されるからです。
あるネットショップでは、次のようなURLパターンがあります。
/user/customers/all/prospects/user/customers/all/current/user/customers/all/returning/user/customers/John/user/customers/Jane
小売業者は次のようなルールを作ることができます。
// newrelic.jsexports.config={ //other configuration rules:{ name:[ { pattern: "/user/customers/all/prospects/", name: "/user/customers/all/prospects" }, { pattern: "/user/customers/all/.*", name: "/user/customers/all" }, { pattern: "/user/customers/.*", name: "/user/customers/:customer" } ] }};
このルールでは、小売業者は3つのトランザクション名を作成します。
/user/customers/:customer
/user/customers/all
/user/customers/all/prospects
小売業者が順序を逆にした場合、ルールは
:customer
でall
トランザクションをキャッチしますが、これはあまり役に立ちません。
リクエストネーミングAPIの読み込み
アプリケーションの他の部分がロードされる前に、New Relic モジュールがブートストラップする必要があるため、New Relic モジュールのロードがアプリケーションの最初に行われるようにしてください。
const newrelic = require('newrelic');
これは、リクエストネーミングAPIを返します。このモジュールは一度だけ初期化されるので、アプリケーション内の複数のモジュールから安全に要求することができます。
APIコールのリクエスト
New Relic の Node.js エージェントの Request 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()
を呼び出すと、互いに上書きされます。リクエストが終了する前に最後に実行されたものが優先されます。
カスタムインストルメントAPIコール
これらのAPIコールを使用して、 カスタムインストルメントでインストルメントを拡張することができます.
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 データストア インストルメンテーション チュートリアルを参照してください。
重要
ES モジュール アプリケーションでのエージェントのブートストラップは CommonJS アプリケーションとは異なるため、このメソッドは ES モジュール アプリケーションではサポートされていないか、または必要ありません。ES モジュール アプリケーションでは、このメソッドが CommonJS アプリケーションで解決する問題をエージェントが補うことができます。
newrelic.instrumentLoadedModule(moduleName, moduleInstance)
instrumentLoadedModule
メソッドを使用すると、アプリのメイン モジュールの最初の行としてrequire('newrelic');
を使用できない状況で、ストック インストルメンテーションを特定のモジュールに追加できます。
// load the agentconst newrelic = require('newrelic');
// module loaded before newrelicconst expressModule = require('express');
// instrument express after the agent has been loadednewrelic.instrumentLoadedModule( 'express', // the module's name, as a string expressModule // the module instance);
重要
このメソッドは、任意のモジュールを計測できません。その目的は、エージェントがプログラムの最初のものとしてロードされなかったために見落とされたモジュールを追加することです。instrumentLoadedModule
メソッドは、エージェントが通常計測するモジュールのみを計測できます。これらのモジュールのリストは、エージェントのlib/instrumentations モジュールで確認できます。
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
が提供されている場合は起動されたときに終了します。
カスタムメトリクスのAPIコール
これらのAPIコールを使用して、 追加の任意のメトリクスを記録する 。
newrelic.recordMetric(name, value)
recordMetric
を使用して、通常は特定の期間に関連付けられたイベント ベースの指標を記録します。name
は、標準のメトリック命名規則に従った文字列でなければなりません。value
は通常は数値ですが、オブジェクトにすることもできます。
value
が数値の場合、イベントに関連する測定値の大きさを表す必要があります。たとえば、特定のメソッド呼び出しの期間です。value
がオブジェクトの場合、count
、total
、min
、max
、およびsumOfSquares
キーをすべて数値で含む必要があります。このフォームは、メトリックを独自に集計し、定期的にレポートするのに役立ちます。たとえば、setInterval
から。これらの値は、同じメトリックに対して以前に収集された値と集計されます。これらのキーの名前は、プラットフォーム API で使用されるキーの名前と一致します。
newrelic.incrementMetric(name, [amount])
incrementMetric
を使用して、単純なカウンターとして機能するメトリックを更新します。選択したメトリックのカウントは、指定された量だけ増加し、デフォルトは 1 です。
カスタムイベントのAPIコール
これらのAPIコールを使用して、追加のイベントを記録します。
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});
トランザクション処理方法
このセクションでは、 newrelic.getTransaction()
を通じて取得できるTransactionHandle
クラス インスタンスによって提供されるメソッドについて詳しく説明します。
これらのメソッドを使用して、現在のトランザクションと直接対話します。
transactionHandle.end([callback])
transactionHandle.end
を使用して、ハンドル インスタンスによって参照されるトランザクションを終了します。
トランザクションが完全に終了すると、 callback
が呼び出されます。最初の引数としてコールバックに渡された終了したトランザクション。
transactionHandle.ignore()
ハンドル インスタンスによって参照されるトランザクションを無視するには、 transactionHandle.ignore
を使用します。
transactionHandle.insertDistributedTraceHeaders(headers)
重要
このAPIは、 分散型トレースが有効になっている必要があります 。
この呼び出しとそのパートナー呼び出し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
メソッドを置き換えます。
以下の例では、空のオブジェクトを指定して insertDistributedTraceHeaders を呼び出すことで、そのトランザクションに適した分散トレースヘッダーと W3C Trace Context ヘッダーが生成されます。
// 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 wellconst headersObject = {};newrelic.startBackgroundTransaction('background task', function executeTransaction() { const transaction = newrelic.getTransaction(); // generate the headers transaction.insertDistributedTraceHeaders(headersObject);});
transactionHandle.acceptDistributedTraceHeaders(transportType, headers)
重要
このAPIは、 分散型トレースが有効になっている必要があります 。
この呼び出しとそのパートナー呼び出しinsertDistributedTraceHeaders
の使用方法に関するコンテキストについては、まずエージェント API で分散トレースを有効にする をお読みください。
transactionHandle.acceptDistributedTraceHeaders
分散トレースに含めるために呼び出されたサービスを計測するために使用されます。insertDistributedTraceHeaders
によって生成されたペイロード、または他の W3C トレース コンテキスト準拠のトレーサによって生成されたペイロードを受け入れることで、トレース内のスパンをリンクします。このメソッドは、着信リクエストのヘッダーを受け入れ、W3C トレース コンテキスト ヘッダーを探し、見つからない場合は、New Relic 分散トレース ヘッダーにフォールバックします。このメソッドは非推奨 (現在はバージョン 7.0.0 で削除されています) を置き換えます。acceptDistributedTracePayload
メソッド。New Relic の分散トレース ペイロードのみを処理します。
transportType
次の文字列のいずれかである必要があります。
- AMQP
- HTTP
- HTTPS
- IronMQ
- JMS
- カフカ
- その他
- キュー
- 不明
headers
着信リクエストのすべてのヘッダーを含むオブジェクトである必要があります。キーは小文字でなければなりません。
次の例は、Kafka メッセージから取得した分散型トレースヘッダーを追加する例です。この例では、受信したKafkaメッセージに分散トレースヘッダーが挿入されていることを想定しています。
// incoming Kafka message headersconst 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()
注意
このメソッドは推奨されておらず、バージョン 7.0.0 で削除されました!使ってください insertDistributedTraceHeaders.
重要
このAPIは、 分散型トレースが有効になっている必要があります 。
この呼び出しとそのパートナー呼び出し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 handlebackgroundHandle.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)
注意
このメソッドは推奨されておらず、バージョン 7.0.0 で削除されました!使ってください acceptDistributedTraceHeaders.
重要
このAPIは、 分散型トレースが有効になっている必要があります 。
この呼び出しとそのパートナー呼び出しcreateDistributedTracePayload
の使用方法に関するコンテキストについては、まずエージェント API で分散トレースを有効にする をお読みください。
transactionHandle.acceptDistributedTracePayload
分散トレースに含めるために呼び出されたサービスを計測するために使用されます。createDistributedTracePayload
によって生成されたペイロードを受け入れることで、トレース内のスパンをリンクします。
transactionHandle.isSampled()
このトレースがサンプリングされているかどうかを返します。
その他のAPIコール
New Relic の Node.js エージェントには、追加の API コールがあります。
newrelic.addCustomAttribute(name, value)
New Relic UI でトランザクションのトレースとともに表示するカスタム属性値を設定します。これは、カスタム属性を設定する場所があるように、トランザクションのコンテキスト内で呼び出す必要があります。カスタム属性は、APM のトランザクショントレースの詳細ビューと、トランザクションのエラーに表示されます。
newrelic.addCustomAttribute('attribute1', 'value1')
注意
カスタム属性を使用したい場合は、NRQL で使用されている予約語を名前を付ける際に使用しないようにしてください。
newrelic.addCustomAttributes(attributes)
New Relic UI でトランザクショントレースとともに表示される複数のカスタム属性値を設定します。属性は 1 つのオブジェクトとして渡す必要があります。これは、カスタム属性を設定する場所があるように、トランザクションのコンテキスト内で呼び出す必要があります。カスタム属性は、トランザクショントレースの詳細ビューとトランザクションのエラーに表示されます。
const attributes = { attribute1: 'value1', attribute2: 2};
newrelic.addCustomAttributes(attributes);
注意
カスタム属性を使用したい場合は、NRQL で使用されている予約語を名前を付ける際に使用しないようにしてください。
newrelic.addCustomSpanAttribute(name, value)
New Relic UI でトランザクション トレース スパンと共に表示されるカスタム スパン属性値を設定します。これは、カスタム スパン属性を設定する場所があるように、アクティブなセグメント/スパンのコンテキスト内で呼び出す必要があります。カスタム スパン属性は、スパン詳細ビューの Attributes セクションに表示されます。
newrelic.addCustomSpanAttribute('attribute1', 'value')
重要
このAPIは、 distributed tracing と span events が有効になっている必要があります。
注意
カスタムスパン属性を使用したい場合は、NRQL で使用されている予約語を名前を付ける際に使用しないようにしてください。
newrelic.addCustomSpanAttributes(attributes)
New Relic UI でトランザクション トレース スパンとともに表示される複数のカスタム スパン属性値を設定します。属性は 1 つのオブジェクトとして渡す必要があります。カスタム スパン アトリビュートを設定する場所を確保するため、これはアクティブなセグメント/スパンのコンテキスト内で呼び出す必要があります。カスタム スパン アトリビュートは、スパン詳細ビューの Attributes セクションに表示されます。
const attributes = { attribute1: 'value1', attribute2: 'value2'};
newrelic.addCustomSpanAttributes(attributes);
重要
このAPIは、 distributed tracing と span events が有効になっている必要があります。
注意
カスタムスパン属性を使用したい場合は、NRQL で使用されている予約語を名前を付ける際に使用しないようにしてください。
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
です。
重要
expected
パラメータには、 Node.js エージェント バージョン 9.12.1 以降が必要です。
例:
try { performSomeTask();} catch(err) { newrelic.noticeError( err, { extraInformation: "error already handled in the application" }, true );}
注意
このメソッドを使用して記録されたエラーは、 ignore_status_codes
構成値に従いません。
newrelic.setErrorGroupCallback(callback)
このメソッドを使用すると、カスタム コールバックを定義してエラー グループ名を生成できます。この名前は、 error.group.name
エージェント属性を介して同様のエラーをグループ化するためにエラー インボックスで使用されます。
指定された関数は文字列を返し、オブジェクトを引数として受け取る必要があります。オブジェクトには、発生したエラーに関連する情報が含まれており、次の形式になっています。
重要
setErrorGroupCallback
を使用するには、 Node.js エージェントのバージョン 9.14.0 以降が必要です。
{ "customAttributes": object, "request.uri": string, "http.statusCode": string, "http.method": string, "error": Error, "error.expected": boolean}
この関数を複数回呼び出すと、このコールバック関数の以前に定義されたバージョンが置き換えられます。
この機能の詳細については、 サンプル アプリを参照してください。
注意
このメソッドは、バージョン7.0.0で削除された非推奨のメソッドです。 transactionHandle.ignore()をご利用ください。
newrelic.setIgnoreTransaction(ignored)
与えられたリクエストを無視するかどうかをモジュールに伝えます。これにより、長いポーリングのある無関係なルートや、時間のかかることがわかっているリクエストを明示的にフィルタリングすることができます。また、他の方法では無視されてしまうリクエストのメトリクスを収集することもできます。
- トランザクションを無視するには、パラメーターを
true
に設定します。これにより、トランザクションが無視されます。 - この関数でトランザクションが無視されないようにするには、パラメーター
false
を渡します。 null
またはundefined
を渡しても、トランザクションが無視されるかどうかは変わりません。
newrelic.setUserID(string)
このメソッドを使用すると、一意の識別子をトランザクション イベント、トランザクション追跡、およびトランザクション内のエラーに関連付けることができます。新しいプロパティ enduser.id
がエラーに追加され、エラー インボックスに報告されます。
重要
setUserID
API には、 Node.js エージェント バージョン 9.13.0 以降が必要です。
newrelic.shutdown(options, callback)
このメソッドを使用して、エージェントを正常にシャットダウンします。両方のパラメーターはオプションです。パラメータを示す概要表を次に示します。
パラメータ | タイプ | 属性 | 説明 |
---|---|---|---|
|
| オプション | シャットダウン オプションを持つオブジェクト |
|
| オプション | エージェント停止時に実行されるコールバック関数 |
以下は、オブジェクトのシャットダウン オプションを示す詳細表です。
オプション名 | タイプ | 属性 | デフォルト | 説明 |
---|---|---|---|---|
|
| オプション |
| シャットダウンする前に、保留中のデータをNew Relicコレクターに送信するかどうかをエージェントに伝えます。 |
|
| オプション |
| シャットダウンを強制するまでのデフォルトの時間。 |
|
| オプション |
| trueの場合、アクティブなトランザクションがなくなるまで、エージェントはシャットダウンしません。 |
例:
newrelic.shutdown({collectPendingData: true, timeout: 10000}, (error) => { process.exit();});
newrelic.getLinkingMetadata()
トレースやエンティティのリンクに使用できるキー/バリューペアを返します。
意味のある値を持つアイテムのみが含まれます。たとえば、分散トレースが無効になっている場合、 trace.id
は含まれません。
newrelic.getTraceMetadata()
現在のトレースIDとスパンIDを含むオブジェクトを返します。
重要
このAPIでは、 分散型トレースが有効になっている必要があります。 さもなければ、空のオブジェクトが返されます。
リクエストの命名と無視のルール
New Relic モジュールへの呼び出しをアプリケーションコードに直接記述したくない場合は、パターンベースのルールを使ってリクエストに名前を付けることができます。ルールには、リクエストの名前を変更するためのものと、New Relic のインスツルメンテーションによって無視されるリクエストをマークするためのものの 2 種類があります。
ここでは、New Relic の Node.js エージェントにおけるルールの構造について説明します。
着信リクエスト 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"}'
オプションのルール属性
追加のオプション属性があります。
オプションのルール属性 | 説明 |
---|---|
| デフォルト:
|
| デフォルト:
これは |
| デフォルトでは、ルールは最初から最後まで順番に評価されます。順序を完全に制御したい場合は、各ルールに 追加属性は無視されます。 |
ネーミングルールのテスト
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'
ここでは、設定ファイルに含まれるルールの全例をご紹介します。
// newrelic.jsexports.config = { // other configuration rules : { name : [ { pattern: "/tables/name-here", name: "/name-hererule1" } ] }};
socket.io を使用している場合は、すぐにルールを無視するユースケースがあります。socket.io の long-polling がレスポンスタイムのメトリクスを支配し、アプリケーションの Apdex メトリクスに影響を与えないようにするには、次のようなルールを追加します。
// newrelic.jsexports.config = { // other configuration rules : { ignore : [ '^\/socket\.io\/.*\/xhr-polling' ] }};
ルールのAPIコール
ここでは、New Relic の Node.js エージェントでルールを命名したり無視したりするための API コールを紹介します。
rules.nameのプログラム バージョン。命名規則が追加されると、Node.js プロセスが再起動されるまで削除できません。また、Node.js エージェントの構成を介して追加することもできます。両方のパラメータが必要です。
rules.ignoreのプログラム版。無視ルールが追加されると、Node.js プロセスが再起動されるまで削除できません。また、Node.js エージェントの構成を介して追加することもできます。このパラメーターは必須です。