Browser エージェント API 経由でデータやイベントの送信

New Relic Browser には、エージェント API があります。これは、New Relic Browser と New Relic Insights へ追加のデータやイベントを送信するのに使えます。例えば、これを使うと以下のようなことが行えます。

要件

The Browser エージェント API は、Browser エージェントが定義している newrelic という名前のオブジェクトを利用します。アプリのページ上でこの API を使うには、Browser エージェントが存在する必要があります。

API の全機能を使うには、バージョンが 593 以上のブラウザのエージェントが必要です。お使いのバージョンを確認し、アップグレードするには、この手順に従ってください。

メソッド

Browser エージェント API を利用することで以下のことができます。

  • セッショントレースに情報を追加する。
  • アプリのユーザーのアクションに関する詳細なタイミングや利用方法に関する情報を Insights で確認するためのイベントを作成する。
  • アプリでキャッチされたエラーの詳細情報を送信する。

Browser エージェント API には、以下のメソッドがあります。

newrelic.addPageAction (name, attributes)

バージョン: nr-593 以上

この機能を使うには、Insights Pro 試用版、もしくは、 Insights Pro 年契約が必要です。

指定した名前と属性で PageAction イベントを New Relic Insights へ送信します。Browser エージェントが追跡しないイベントを追跡したい場合に役立ちます。例えば、購読ボタンのクリックやチュートリアルへのアクセスなどです。また、この機能は、シングルページや AJAX を多用したアプリのルート変更の追跡にも役立ちます。

この API コールは、様々なデフォルト属性と共に PageAction イベントを Insights へ送信します。送られたイベントは Insights で問い合わせができます。PageAction イベントは、Insights へ 10 秒毎に送信されます。ブラウザごとに 10 秒の収穫サイクルあたり最大 20 イベントを送信します。20 イベントに達すると、それ以上はキャプチャされません。詳しくは、JavaScript Browser API 経由のカスタムイベントの追加をご覧ください。

パラメーター
パラメーター データ・タイプ 説明
name 文字列 アクションの名前やカテゴリ名。actionName 属性として、Insights へ送信される。
属性/値の名前をつける際は、NRQL の予約語 にある名前は使わないようにしてください。
attributes JSON オブジェクト 1 つ以上のキー/値をもつ JSON オブジェクト。例: {key:"value"}。キーは、指定した値を持つ独自の PageAction 属性として Insights に送信します。
属性の名前をつける際は、NRQL の予約語 にある名前は使わないようにしてください。
ユーザーが、Try Me! リンクを押した際に、PageAction イベントを記録する例です。イベントは、clickedTryMe という actionName で記録されます。

<a href="/demo" id="try-me">Try Me!</a>
<script>
    document.getElementById('try-me').addEventListener('click',function (e) {
        newrelic.addPageAction('clickedTryMe');
    })
</script>

Try Me! ボタンがクリックされた数を問い合わせる際の、NRQL は以下のとおりです。

SELECT count(*) FROM PageAction WHERE actionName='clickedTryMe' SINCE 1 hour ago
ユーザーが、copy-text クラスの要素を押した際に、PageAction イベントを記録する例です。actionName は、copy-text-button、値は、

copy-text クラスの要素をクリックしたときに PageAction イベントを送信する例です。actionNamecopy-text-button であり、値は、処理結果が、successerror に応じて対応する Result 属性を送信します。

$('.copy-text').click(function (){
    var clipboard = new Clipboard ('.copy-text');
    clipboard.on('success', function(event) {
      // 処理を行う
      // Insights へデータ送信
      if (typeof newrelic == 'object') {
        newrelic.addPageAction('copy-text-button', {result: 'success'});
      }
    });
    clipboard.on('error', function(event) {
      // 処理を行う
      // Insights へデータ送信
      if (typeof newrelic == 'object') {
        newrelic.addPageAction('copy-text-button', {result: 'error'});
      }
    });
});

そして、以下の NRQL を利用すると、Insights にて過去 30 日のボタンクリックの成功とエラーの数の内訳を円グラフで表示できます。

SELECT count(*) AS 'Clicks' FROM PageAction WHERE actionName = 'copy-text-button' FACET result SINCE 30 days ago

他にも、過去30日間でもっともコピーボタンがクリックされたページを見るには、以下のクエリで確認できます。

SELECT count(*) AS 'Clicks' FROM PageAction WHERE actionName = 'copy-text-button' FACET currentUrl SINCE 30 days ago
フォームでの入力をキャプチャ
Signup フォームでのユーザーの入力(メールアドレス)をキャプチャする例です。actionNameuserSignup というイベントを記録します。

<form action="/signup" id="myform">
   <input id="email" name="email">
   <input type="submit" value="Signup">
</form>
<script type="text/javascript">
    document.getElementById('myform').addEventListener('submit', function (e) {
        var email = e.target.elements['email'].value;
        newrelic.addPageAction('userSignup', {email: email});
    })
</script>

以下の NRQL で収集したメールアドレスを確認できます。

SELECT uniques(email) FROM PageAction WHERE actionName='userSignup' SINCE 1 hour ago
newrelic.addToTrace (obj)

バージョン: nr-593 以上

ブラウザのセッショントレースが、進行中である場合、以下に記載した、ユーザーが定義した名前、開始時刻、他のオプションのフィールドを持つオブジェクトをこれに追加します。
トレースが進行中でない場合は、この呼び出しを行っても、トレースを取得しません。

セッショントレース内のカスタムイベントは、他のユーザーのアクション、エラー、そのトレース内のデフォルトのイベントのコンテキストを参照できます。このイベントは、ブラウザのセッショントレースの詳細に表示されます。

PageAction として New Relic Insights に同じイベントオブジェクトを送信する場合は、type 属性を省略してください。type 属性が含まれている場合、そのイベントオブジェクトはイベントタイプを上書きして、PageAction イベントが誤って送信されることになります。代わりに、イベント情報の name 属性を使用してください。
パラメーター
パラメーター データ・タイプ 説明
obj JavaScript オブジェクト 必須: 名前/値のペア: name, start.

オプション: 名前/値のペア: end, origin, type.

詳しくは、を見てください。

var obj = {
  // 必須
  name: 'Event Name',
  start: 1417044274239, // エポック時間からの時間。ミリ秒。

  // オプション
  end: 1417044274252,
  // Time in ms since epoch. Defaults to same as start resulting in trace object with a duration of zero.
  origin: 'Origin of event',
  origin: 'Origin of event',
  // デフォルトは空文字
  type: 'What type of event was this'
  // デフォルトは空文字
}
newrelic.finished (time)

バージョン: nr-593 以上

このメソッドは 2 つのことを行います。

  • セッショントレースが実行中の場合、finished イベントを現在の ブラウザのセッショントレースに追加します。
  • finished という名前で PageAction イベントを New Relic Insights へ送信します。 (Insights Pro 試用版、または Insights Pro 年サブスクリプションが必須)

ページ読み込みごとに、一度だけこれを呼び出すことができます。これは、その読み込み用に記録されたページ読み込みタイミングの他のメトリクスには影響しません。この API を呼び出す目的は、ページロード・イベントの前後で、指定した条件に応じて、ページが終了する時刻を記録することです。(例えば、非同期にコンポーネントの読み込みが多いページなど)

パラメーター
パラメーター データ・タイプ 説明
time 数値 (UNIX エポック時間からの経過時間。単位:ミリ秒) オプション: デフォルトは、呼び出し時間

ページが独自の基準に基づいて「完成」した時刻をマークします。

newrelic.noticeError (error)

バージョン: nr-411 以上

アプリが以下の要件を満たしていることを確認してください。

  • Browser 監視機能が、有効であること。
  • JavaScript エラー監視機能が、有効であること。

アプリが扱ったエラーやその他の各種エラーを通知、記録するために、この API コールを利用します。エラーをキャッチしたり、処理したが、それによって、アプリの動作を中断させずに、それを認識したいときにこの API は便利です。

また、スクリプトの初期化中やインライン・イベントハンドラで発生したエラーなど、詳細な情報なく報告されるエラーを通知するのにも使えます。このエラーは、New Relic が通常検知する他のエラーと同様に、JavaScript errors ページに表示されます。

パラメーター
パラメーター データ・タイプ 説明
error 文字列 JavaScript errors ページでデータを解析する際に使用できる意味のあるエラーメッセージを指定します。
致命的でないエラーのキャプチャ
以下は、エラーをキャッチした際に、newrelic.noticeError API を使って、アプリの実行を中断せずに、エラーを報告する方法の例です。この API は、ユーザーがアプリの体験にそれほど影響のないエラーが発生した際に、開発者にそのエラーを報告したい場合に便利です。以下のコードは、不正な JSON だった場合に、安全なデフォルトの foo オブジェクトを使うようにしている例です。

var foo;

try {
  foo = JSON.parse('{ "bar"');
} catch (err) {
  //New Relic にキャッチしたエラーを送信。
  newrelic.noticeError(err);

  foo = {bar: 'default value'};
}

alert(foo.bar);
エラー付きのコールバックの例
Browserify 開発や Node.js によって普及した、エラーとレスポンスのパターンのコールバックを使用しているときに、New Relic にエラーを報告する方法の例です。alert(body); の部分は、任意のコードに置き換える事ができます。

var xhr = require('xhr');

xhr('http://localhost:8080', function (err, resp, body) {
  //スローされないエラーを New Relic へ送信
  if (err) return newrelic.noticeError(err);
  //成功レスポンスを処理
  alert(body);
});
Promise ベースの API の例
Promises は、非同期のインタラクションを扱うためのパターンです。これにより、非同期エラーの扱いが簡単になります。しかし一方、エラーを完全に無視したり、アプリが壊れているのに、開発者が気づかない状態も簡単につくれます。以下は、見落しを防ぐために、New Relic に非同期エラーを報告する例です。

var rest = require('rest');

rest('/').then(function (res) {
  //成功レスポンスを処理
  alert(res.entity);
}, function (err) {
  //New Relic にエラーを送信
  newrelic.noticeError(err);
});
Browser の制限 (Safari と Internet Explorer のみ)

エラーがスローされない場合、スタックトレースはありません。newrelic.noticeError API を使って、全てのブラウザのタイプでスタックトレースをレポートしたい場合、API へエラーを渡す前に、手動でエラーをスローし、キャッチする必要があります。

try {
  throw errorObject
} catch (err) {
  newrelic.noticeError(err)
}
newrelic.setCustomAttribute (name, value)

バージョン: nr-593 以上

ユーザーが定義した属性の名と値をページ上のイベントに追加します。PageView イベントに指定の属性を含めるために、ウィンドウの load イベントが発生する前(データ送信時点) に、この呼び出しを行う必要があります。一旦、属性が設定されると、ページがリロードされるか、属性が手動で解除されるまで、全 PageAction イベントで記録され続けます。(PageAction イベントを使うには、New Relic Insights の Por 試用版または Pro 年間サブスクリプションが必要です)

パラメーター
パラメーター データ・タイプ 説明
name 文字列 属性の名前。PageView イベントの列として表示されます。それを使い続けている場合は PageAction イベントの列としても表示されます。
属性/値のキーとして、NRQL 予約語は使わないようにしてください。
value 文字列 属性の値。PageView イベントで指定した属性名の列の値として表示されます。使い続けている間は、PageAction イベントの列にも表示されます。カスタム属性の値は、複雑なオブジェクトを指定できません。文字列や数値などの単純なタイプのみ指定できます。
属性/値のキーとして、NRQL 予約語は使わないようにしてください。

Drupal で生成されたページの以下の HTML 要素の値を取得するのに、javascript/jQuery を使い、カスタム属性として、取得した値を Insights に報告します。すると、Insights でPageView イベントと PageAction イベントへのクエリからその値を取得することができます。

  • <link rel="shortlink" href="/node/1111" />
  • <h1>Using NRQL</h1>
var node_id = '';
node_id= jQuery("link[rel='shortlink']").attr("href");
var node_title = '';
node_title= jQuery('h1').text();

if (typeof newrelic == 'object') {
  newrelic.setCustomAttribute('nodeId', node_id);
  newrelic.setCustomAttribute('title', node_title);
}
newrelic.setPageViewName (name[, host])

バージョン: nr-593 以上

URL の構造によるグループ化が役に立たない場合や、ルーティング情報が格納されている URL の一部がキャプチャされていない場合は、ページ名をカスタマイズすることにより、より効果的にページビューをグループ化できることがあります。指定されたページビューの名前は、New Relic Browser と New Relic Insights で使用されます。

代わりに、ページのURLのカスタマイズされたページビュー名を使用するには、スラッシュで区切られた文字列として名をフォーマットします。それは正しく表示するためには、負荷イベントが発生する前に、この呼び出しを行います。ページ URL をページビューの名前として利用する代わりに、カスタマイズしたページビュー名を使うには、スラッシュで区切った文字列の名前を指定します。正確に表示されるように、この API コールが、load イベントが発行サれる前に呼び出すようにしてください。

パラメーター
パラメーター データ・タイプ 説明
name 文字列 New Relic Browser や New Relic Insights で表示したいページ名。
host 文字列 オプション:デフォルトは、 custom.transaction

このカスタムトランザクションをより細かくグループをするには、独自の host を指定します。そうでない場合、ページビューは、デフォルトのドメイン custom.transaction が割り当てられます。セグメントが表示されない場合は、URL whitelist setting で Whitelist segments に名前にあるセグメントを追加する必要があります。

関連情報

関連する情報は以下のとおりです。