Browser Agent and SPA API
Browser Agent and SPA API

Browser Agent and SPA API

“https://docs.newrelic.com/docs/browser/new-relic-browser/browser-agent-apis/new-relic-spa-api\n【SPA API】

『この機能の利用は《サブスクリプションレベル》に依存します。SPAモニタリングは【New Relic Browser Pro】でのみ利用できます。』

Browserの《シングルページアプリケーション(SPA)モニタリング》を利用している場合、SPA APIを使って特定のブラウザーインタラクションのモニタリングをカスタマイズできます。New Relicが自動的に記録しないインタラクションを監視するのに役立ちます。その理由は、結果としてルート変更をしないからです(例えば、動的に更新されるウィジェットが一例です)。また、このAPIを使うと、監視するほど重要ではないと思われるインタラクションのデフォルトのモニタリグ機能をオフにできます。New Relic SPAモニタリングがどうように機能するかをもっと詳しく知りたい人は、《SPAデータコレクションを理解する》を見てください。

【全て表示】 【全て非表示】

【newrelic.interaction()】

『newrelic.interaction()』は利用中のインタラクションと結びついた新規のAPIオブジェクトを返します。New Relicがインタラクションを監視していない時にnewrelic.interactionがコールされると、新規のインタラクションが作成されます。同一のインタラクションの中で再度コールされると、利用中のインタラクションを参照する新規のオブジェクトが作成されます。
SPA APIメソッドは『newrelic.interaction()』で利用できます。また、このメソッドは変数に割り当てたハンドルでも利用できます。以下は例です。

『myInteraction = newrelic.interaction()myInteraction.save()』

名前を付けたハンドルを保存し、インタラクションの外部から利用できますが、インタラクションが終了するとメソッドは機能しなくなります。

【全て表示】  【全て非表示】

【処理結果】

このメソッドは特定の『BrowserInteraction』に結びついたAPIオブジェクトを返します。同一の『BrowserInteraction』に対してこのメソッドがコールされるたびに新規のオブジェクトが作成されますが、その場合でも同一のインタラクションを参照します。

【newrelic.interaction().setName(string NAME, string TRIGGER)】

エージェントバージョン963またはそれ以降

このメソッドはブラウザーインタラクションの名前やトリガーの設定に使用されます。この名前は『BrowserInteraction』イベントの中で『browserInteractionName』属性として公開され、UIにおけるグループ化に利用されます。

デフォルトでは、『browserInteractionName』は紐づいたURLやルートにちなんで名付けられます。ルート変更やURL変更ではないインタラクションを記録したいと考えている場合は、『setName』を使用してください。

《setCurrentRouteName API》は利用中のルートに名前を付けます。『setName』および『setCurrentRouteName』 の両方を使用する場合、インタラクションの名前としては『setName』が優先します。しかし、『previousRouteName』や『targetRouteName』属性は『setCurentRouteName』に渡された値を利用して設定されます。

これらのメソッドを組み合わせて利用すると、UIにおいてフィルタリングやグループ化をする場合にさまざまな興味深い選択肢が取れます。一例として、『LikeButtonClick』など特定のタイプのインタラクションまでフィルタリングし、『targetRouteName』によりグループ化し、どのルートがもっとも『LikeButtonClick』インタラクション数が多いかを確認できます。

【処理結果】

このメソッドは『newrelic.interaction()』により作成された同一のAPIオブジェクトを返します。

【パラメーター】
【パラメーター】 【データタイプ】  【説明】
NAME  文字列 ヌルでない場合、このパラメーターは『BrowserInteraction』イベントの中の『browserInteractionName』属性を設定します。名前が設定されていない場合、名前は『targetGroupUrl』属性を使って設定されます。

TRIGGER  文字列 ヌルでない場合、『BrowserInteraction』イベント上でtrigger属性を設定します。

【例】

インタラクションへのカスタム名の追加の例

『document.getElementById(‘subscribe’).addEventListener(‘submit’, () => {
newrelic.interaction().setName(‘createSubscription’)
createSubscription()
})』

【newrelic.setCurrentRouteName(string ROUTE NAME)】

バージョンnr-998またはそれ以降

『このメソッドは現在、SPA 『BrowserInteraction』イベントにのみ適用されています。』

このメソッドは利用中のルートに名前を付けます。このメソッドは以下のような場合、役立ちます。ルートにデフォルトよりも正確な名前を付ける場合
デフォルトでは別のルートを使ってグループ化されうるルートを監視する場合

『setCurrentRouteName』と『setName』は別のものです。後者はルートではなくブラウザーインタラクションに名前を付けるものです。これらがどのように組み合わせて利用されるかについては、《setName APIエントリー》を参照してください。

このAPIを使うと、以前のルートやターゲットルートを追跡する2つの新規のカスタム属性を作成できます。ルートはそれぞれ、『previousRouteName』と『targetRouteName』が対応します。このAPIを利用する場合、『browserInteractionName』属性は『targetRouteName』の値を取ります。ブラウザーインタラクション名を設定するために『setName』が利用される場合、setNameが優先します。

このAPIは『BrowserInteraction』イベントの名前属性を決定するのに利用されるため、『BrowserInteraction』イベントが必ず正しい属性になるように、【ルート変更があるたびに毎回呼び出される必要があります】。この方法を取らずにデフォルトの命名方法に戻す場合は『newrelic.setCurrentRouteName(ヌル)』をコールします。

『setCurrentRouteName』に渡されるルート名はどのような文字列でも問題ありませんが、特定のリソースよりもルートパターンを表すものが推奨されます。例えば、『/users/123』よりも『/users/;id』のほうが好ましいです。

【全て表示】  【全て非表示】

【パラメーター】
【パラメーター】  【データタイプ】  【説明】
『name』  文字列  ページの現在のルート名

【例】

以下のコードは利用中のルート名の設定の例です。

『router.onChange(function (route) {
newrelic.setCurrentRouteName(route.name)
})
********』

【newrelic.interaction().save()】

エージェントバージョン963またはそれ以降

このメソッドはインタラクションが終了すると、インタラクションが必ず保存されるようにするものです。初めてページを読み込む場合またはURLもしくはハッシュが変更される場合、インタラクションは通常、保存されNew Relicに送信されるだけです。このビヘイビアーを上書きし、インタラクションを確実に記録するにはこのメソッドをコールする必要があります。

【全て表示】 【全て非表示】

【処理結果】

このメソッドは『BrowserInteraction』イベントと紐づいた『newrelic.interaction()』により作成された同一のAPIオブジェクトを返します。

【例】

以下はカスタムインタラクションを保存するコード例です。

『window.addEventListener(‘scroll’, () => {
if (atBottomOfPage()) {
newrelic.interaction() // このインタラクションの監視を開始
.setName(‘loadNextPage’) //インタラクションの名前を設定
.save(); // 終了する場合にこのインタラクションをBrowserInteractionイベントとして必ず保存する
loadNextPage() //次のページのロードを開始
}
})
********』

【newrelic.interaction().ignore()】

エージェントバージョン963またはそれ以降

このメソッドを利用すると、インタラクションが無視されます。つまり、データが保存されたり、New Relicに送信されないことを意味します。また、このメソッドは『save』に対する過去のまたは未来のコールを無視します。

【全て表示】 【全て非表示】

【処理結果】

このメソッドは『newrelic.interaction()』が作成する同一のAPIオブジェクト
を返します。

【例】

インタラクションを無視するコード例

『router.addRoute(‘/uninteresting-route’, () => {
newrelic.interaction() //現在のインタラクションのハンドルを取得
.ignore() // このインタラクションが確実に保存されないようにするためこのインタラクションを無視
renderUninterestingRoute() // ルートを変更する
})
********』

【newrelic.interaction().end()】

エージェントバージョン963またはそれ以降

このメソッドは現在進行中のインタラクションを終了させます。その後に起こるコールバックやリクエストはインタラクションに含まれません。

【全て表示】 【全て非表示】

【処理結果】

このメソッドは『newrelic.interaction()』が作成する同一のAPIオブジェクトを返します。

【例】

インタラクションを早期に終了するコードの例

『router.addRoute(‘/profile’, () => {
startSlowBackgroundAjax() //インタラクションの終了後に継続する作業を開始する
renderProfileComponents().then(() => { // インタラクションの一部となっている作業をする
newrelic.interaction().end() //ページの持つ重要なコンポーネントがレンダリングを完了したらインタラクションを終了させる
})
})
********』

【newrelic.interaction().setAttribute(string KEY, any VALUE)】

エージェントバージョン963またはそれ以降

このメソッドはインタラクションにカスタム属性を追加します。インタラクションが保存された場合、この属性は結果として生じる『BrowserInteraction』イベント上で新規のプロパティとして表示されます。『newrelic.setCustomAttribute(…)』を使って追加される属性とは違い、インタラクションに追加される属性は現在利用中のインタラクションにのみ適用され、『PageAction』イベントには追加されません。

このメソッドを利用して設定されたカスタム属性は『newrelic.setCustomAttribute(…)』をコールすることにより設定されるカスタム属性およびサーバーサイドエージェントにより設定されるカスタム属性とマージされます。SPA APIを使って設定された『BrowserInteraction』属性の優先度はもっとも高く、別の2つの方法で設定される属性よりも優先します。『newrelic.setCustomAttribute(…)』により設定される属性はその次に優先し、サーバーサイドのカスタム属性よりも優先されます。サーバーサイドを設定するカスタム属性の優先度はもっとも低いです。

【全て表示】【全て非表示】

【処理結果】

このメソッドは『newrelic.interaction()』が作成する同一のAPIオブジェクトを返します。

【パラメーター】
【パラメーター】  【データタイプ】 【説明】
KEY 文字列  このパラメーターは『BrowserInteraction』イベント上で属性名として利用されます。
VALUE Any このパラメーターは『BrowserInteraction』イベント上で属性の値として利用されます。文字列や数字、ブール値、またはオブジェクトになる可能性があります。オブジェクトである場合は、JSON文字列としてシリアル化されます。

【例】

カスタム属性を設定するコード例

『router.addRoute(‘/profile’, () => {
const user = getCurrentUser()
newrelic.interaction()
.setAttribute(‘username’, user.username)
.setAttribute(‘userId’, user.id)
renderProfile(user)
})
********』
\n【newrelic.interaction().getContext(function CALLBACK)】

エージェントバージョン963またはそれ以降

このメソッドは利用中のインタラクションと紐づいたコンテキストオブジェクトを使って非同期に呼び出されるコールバックを利用します。このオブジェクトは利用中のインタラクションと紐づいた値を保存するために利用されます。また、このオブジェクトはインタラクション全体で共有され、複数の場所で利用される可能性がありますが、この仕組みによりインタラクション全体のデータを集計できます。

【全て表示】 【全て非表示】

【処理結果】

このメソッドは『newrelic.interaction()』が作成する同一のAPIオブジェクトを返します。

【パラメーター】
【パラメーター】  【データタイプ】 【説明】
CALLBACK  関数  インタラクションコンテキストオブジェクトだけを引数として受け取る関数。

【例】

インタラクションコンテキストを利用してデータを伝達するコード例

『router.addRoute(‘/products/{productId}’, params => {
newrelic.interaction().getContext(ctx => ctx.productId = params.productId)
renderProduct(params.productId)
updateHash()
})

window.addEventListener(‘hashchange’, (ev) => {
const interaction = newrelic.interaction()
interaction.getContext(ctx => {
if (ctx.productId) {
interaction.setAttribute(‘productId’, ctx.productId)
}
})
})
********』

【newrelic.interaction().onEnd(function CALLBACK)】

エージェントバージョン963またはそれ以降

このメソッドは『getContext』メソッドと機能が似ています。インタラクションが終了すると呼び出されるコールバックを利用します。このコールバックには『getContext』に与えられるコールバックに渡されるのと同一のオブジェクトが渡されます。このコールバックを利用すると、関数の最後の部分にあるイベントを変更できます。例えば、イベントにカスタム属性を追加できます。

インタラクションを修正するためのメソッド(『setName』や『save』、『ignore』、『setAttribute』)を呼び出す場合もあるでしょう。しかし、非同期のデメリットがあるメソッド(『getContext』や『onEnd』、『createTracer』)を利用しても問題にはなりません。

【全て表示】 【全て非表示】

【処理結果】

このメソッドは『newrelic.interaction()』が作成する同一のAPIオブジェクトを返します。

【パラメーター】
【パラメーター】  【データタイプ】 【説明】
CALLBACK  関数  インタラクションコンテキストオブジェクトだけを引数として受け取る関数。

【例】

インタラクションの末尾に属性を設定する例

『// router.js
router.addRoute(‘/dashboard’, () => {
const interaction = newrelic.interaction().onEnd(ctx => {
interaction.setAttribute(
‘averageChartLoadTime’,
ctx.totalChartLoadTime / ctx.chartLoadCount
)
})
getCharts().forEach(loadChart)
})

// chart-loader.js
function loadChart (chart) {
const start = Date.now()
chart.load().then(() => {
const loadTime = Date.now() – start
interaction.getContext(ctx => {
ctx.totalChartLoadTime = (ctx.totalChartLoadTime || 0) + loadTime
ctx.chartLoadCount += (ctx.chartLoadCount || 0) + 1
})
}
}
********』

【newrelic.interaaction().createTracer(string NAME, function CALLBACK)】

エージェントバージョン963またはそれ以降

このメソッドはインタラクションのサブコンポーネント別に時間を測るものです。各々のサブコンポーネはコールバックが実行されるまでの待ち時間とコールバックが呼び出された場合のコールバックのJS実行時間の両方を測定します。また、このメソッドは計測されていない非同期メソッドにより生まれる非同期のギャップを埋め合わせるためにも利用されます。

利用中のインタラクションが保存されると、《BrowserTiming》 Insightsイベントが作成され、タイミングの情報が詳細タブに表示されます。

このメソッドはラップされたコールバックメソッドを返しますが、そうするにはコードから呼び出す必要があります。返されたラップされたコールバックが呼び出されると、3つの作業をします。

1. カスタムトレーサーの非同期部の終了時間の部分を記録する。
2. 同一の引数とコンテキストを利用してcreateTracerに渡された元のコールバックを実行する。
3. 元のコールバックの実行時間を測定する。

『createTracer』を実行する『BrowserInteraction』は『BrowserTiming』イベントを作成します。コールバック中に新規のXHRまたはカスタムトレースが作成された場合はインタラクションの一部に入れられます。インタラクションはすべてのトレースが完了するまで完了したとはみなされません。トレーサーはこのようにしてエージェントがデフォルトでは扱っていない非同期関数をラップできます。名前が付けられていない場合、インタラクションツリーにノードは追加されず、コールバックの時間は親ノードに属します。

【全て表示】  【全て非表示】

【処理結果】

このメソッドは非同期時間を終了させ、『createTracer』に渡されたコールバックをコール(および時間測定)します。

【パラメーター】
【パラメーター】  【データタイプ】 【説明】
NAME 文字列 このパラメーターはトレーサーの名前として利用される。
CALLBACK 関数 非同期作業部の末尾で同期作業を実行する部分を含むコールバック。このコールバックは『newrelic.interaction().createTracer』をコールすることで返されるラッパー関数をコールして実行できる。

【例】 【同期されたコードをトレースする】

特定のJavaScript関数のコールにかかる時間がどの程度か単純に測定したいだけの場合、『createTracer』に関数をコールバックとして渡せば返されたラッパーコールバックを即座に呼び出せます。

『newrelic
.interaction()
.createTracer(‘customSegment’, function myCallback () {
// … do your work …
})()』

このシナリオでは、結果として生じるカスタムトレーサーの非同期待ち時間はごくわずかとなり、また、同期待ち時間は『myCallback』の実行時間に等しくなります。

【例】 【インストルメント化されていない非同期APIを追跡する】

デフォルトでは、New Relic agentはもっとも一般的な非同期関数(『setTimeout』など)をたくさんラップしています。しかし、通常の使い方がされている関数もあり(例えば、『requestAnimationFrame』)、ケースによってはそうなっている原因が簡単に特定できない場合もあります(例えば、カスタムRPCを『websockets』へ実装する場合)。このような場合、これらのインストルメント化されていない関数に対するコールバックがインタラクションの一部とみなされていないことを確認するために『createTracer』を利用します。

コールバックを受け取り、未来のどこかでこのコールバックを非同期に実行する関数、『doAsyncWork』を利用するとします。そして、『doAsyncWork』を呼び出し、コールバックが実行されるまでの時間(非同期待ち時間)とコールバックを実行するために必要な時間(同期コールバック時間)の両方の時間を測りたいと考えます。

New Relic Browser agentが初めからラップしている非同期API(例えば、『setTimeout』や『setImmediate』、『Promise』、『fetch』、『XMLHttpRequest』)に基づいたすべての非同期スケジューリングシステムに対して『createTracer』を使用する必要がないことに注意してください。これらのAPIが作成している非同期バウンダリーはNew Relic Browser agentが自動的に補完します。

以下のコードを使えば、createTracerを利用して目的を達成できます。

『var wrappedCallback = newrelic
.interaction()
.createTracer(‘customSegment’, doTheWork)

doAsyncWork(wrappedCallback)

function doTheWork() {
// … do your work …
}』

以下の図はイベントのタイムラインを示したものです。

《トレーサータイミングの概要》
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n”