Insights APIを使ったカスタムイベントの挿入

Insights API を使ってカスタムイベントを挿入することで、カスタムイベントを保存できます。保存したイベントデータはクエリを使って取得できます。カスタムイベントは、New Relic Insights に新規のイベントタイプとして表示されます。また、Insights の イベントデータエクスプローラーを使って、レポートされてきているイベントを確認したり、クエリを作成することができます。

エージェント API がサポートされているエージェントから適切なエージェントAPIを使用して、直接カスタムイベントを記録することができます。例えば、 (New Relic APM エージェント経由で追加される) Transactions や (New Relic Browser エージェント経由で追加される) PageViews

Insert keys を登録する、または、Insights API 経由でカスタムイベントを追加するには、有料の Insights サブスクリプションが必要となります。

イベントの挿入

New Relic Insights アカウントにイベントを挿入する手順は以下のとおりです。

  1. Insights API の Insert Key(インサートキー)を登録する
  2. アプリケーションの計測、APIの問い合わせ、その他の方法を実行することでイベント用のJSON を生成する。
  3. cURL を使用して POST リクエストを Insights の HTTPS エンドポイントに JSON 形式で送信する。

この方法を利用して Insights アカウントに直接イベントを挿入します。また、 デフォルトのトランザクションページビューイベントに追加属性を加えるためのカスタム属性も使えます。

Insightsでは、カスタムイベントで利用可能なサイズ、率、文字を制限しています。他の Insights のイベントと同様に、カスタムイベントは、作成された後に更新や削除することはできません。

API キーの登録

インサートキーを使うと、Insights にイベントを追加できるようになります。1つのインサートキーで送信された複数のイベントの種類を持つことができます。セキュリティ確保の観点から、アプリケーションやデータソースが別であれば、それごとに別のインサートキーを​​使うことをお薦めします。

インサートキーを追加する手順は以下のとおりです。

  1. New Relic のメニューバーから、Insights > Manage data > API keysを選択する。
  2. API key management から、 Insert Keys の見出し横にあるプラスサインを選択する。
  3. キーの短い説明を入力します。
  4. Save your notes [メモを保存]を押す。

Edit Insert key [インサートキーの編集] ページには、そのキーを利用してデータを挿入するために必要なの cURL コマンド一覧が表示されます。

screen-insights-edit-insert-key
Manage Data > API Keys > Edit: Insert Key の作成及び編集を行う場合、編集ページは、キーとそのキーを使用した HTTP リクエストの例の両方を表示します。

アプリケーションの計測

New Relic Agent から直接、APM が計測しているアプリからカスタムイベントを追加できます。また、Insights JavaScript API を使って、ブラウザからイベントを追加することもできます。

JSON フォーマット

ここでの Insights に送信する典型的な JSON のデータセットの例です。この呼び出しは、JSON 配列として「Purchase」タイプの2つのイベントを送信します。JSON 配列を使うと、複数のイベントを1つの HTTTP コールから追加することができます。

[ { "eventType":"Purchase", "account":3, "amount":259.54 }, { "eventType":"Purchase", "account":5, "amount":12309, "product":"Super expensive thing" } ]

JSON を生成する際は、適切なフォーマットであることを確認してください。

  • eventType は必須です。Insights におけるイベントの名前です。
  • Floats は、"label":value の形式と取ります。
  • Strings は、"label":"value" の形式と取ります。
  • Insights は、Key/Value ペアのみ受け付けます。Map や Object、配列には対応していません。データの種類としては、浮動小数点と文字列のみ、サポートしています。
  • Insights は Key/Value ペアだけではなく、map/object や配列も受け入れています。
  • 引用符で挿入された数値は、数値ではなく、文字列として扱われます。
  • 日付情報の属性は、未フォーマットの Unix タイムスタンプでなければなりません。Unix エポックからの相対時間として秒かミリ秒で日付属性を定義します。日付属性は、Manage Data > Data Formatter からタイムスタンプとしてフォーマットをします。

タイムスタンプ

特に指定がない限り、送信されたイベントのタイムスタンプは、それが New Relic に送信された時間となります。イベントで別のフィールドを時間として使う場合は、timestamp 属性を指定します。タイムスタンプは、New Relic にイベントが提出された時点から24時間以内でなければなりません。

timestamp 属性は、フォーマットしていない UNIX タイムスタンプを取ります。Unix エポックからの相対時間として秒かミリ秒でタイムスタンプを定義します。

イベントの送信

データは、シンプルな HTTP リクエストを使用した JSON フォーマットで Insights に送信します。

Insert Key ページでは、サンプルの cURL クエリが表示されます。テンプレートとして使用できます。

cat example_events.json | curl -d @- -X
  POST -H "Content-Type: application/json" -H "X-Insert-Key: YOUR_KEY_HERE"
  https://insights-collector.newrelic.com/v1/accounts/(あなたのアカウントID)/events

HTTP リクエストを生成する際に、適切にフォーマットされていることを確認します。データの記録に失敗した場合にイベントタイプが適切でない場合、Insights はエラーをレポートしないことがあります。

  • X-Insert-Key には、正しい Insert Key を指定してください。
  • Content-Type には、application/json を指定して下さい。
  • POST を使ってください。PUTGET は使えません。

HTTP/1.1 持続的接続 [英語] をサポートしています。これはイベント負荷が高い状況で、クライアント側のパフォーマンスを管理するのに便利です。

制限と制限されている文字

Insights はカスタムイベントのサイズやレートに制限を設けています。

  • 属性: 1イベントあたり最大 255
  • 文字列属性: 最大長 4kb
  • バッチの合計数: 1コールあたり 1000 イベント
  • バッチの合計サイズ: 1コールあたり最大 5Mb

カスタムイベントを挿入するときには、次の文字ルールに則ってください。

  • accountId: 整数であること。
  • appId: 整数であること。
  • eventType: アルファベットと数値、_ アンダースコア、 : コロンの組み合わせを使えます。
  • timestamp: 64 ビット整数。サーバー上の現在時刻の +/- 1日 (24時間)以内。

予約語

以下の単語は NRQL と Insights が使います。属性の名前として使用しないでください。使われた場合は、結果がおかしくなる可能性があります。注: これは完全なリストではありません。

NRQL 構文の用語は、属性名に使用することができますが、`LIMIT` のようにバッククォートで囲む必要があります。以下が、NRQL 構文用語です。

ago, and, as, auto, begin, begintime, compare, day, days, end, endtime, explain, facet, from, hour, hours, in, is, like, limit, minute, minutes, month, months, not, null, offset, or, second, seconds, select, since, timeseries, until, week, weeks, where, with

これが予約語の全てというわけではありません。New Relic Insights が開発中である限り、MySQL 予約語 [external link] は使わないでください。

関連情報

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