Event APIを使ったカスタムイベントの送信

New Relic Event APIでは、POSTコマンドを使用してカスタムイベントをアカウントに送信できます。New Relic Insightsにおいて、こうしたイベントは新規のイベントタイプとして表示されます。NRQLもしくはInsights Data Explorerを使用することで、カスタムデータのサンプリング、クエリ、そして視覚化が可能となります。

お使いのアカウントがEUデータセンターでデータをホストする場合は、適切なEUリージョンアカウント向けAPIエンドポイントを使用していることを確認してください。

詳しくは、New Relic UniversityのAdding custom events with the Insights APIチュートリアルを参照してください。もしくは、完全オンラインコースの Custom Data with Insightsに直接アクセスしてください。

基本ワークフロー

Event APIは、非同期のエンドポイントです。このため、大容量のPOSTを、非常に低いレスポンスレイテンシで確実に送信できます。

ご利用のNew Relicアカウントにカスタムイベントを送信するには:

  1. Event APIの Insertキー登録します。
  2. カスタムイベントまたは属性を作成する前に、New RelicのNRQLおよびInsightsが使用する予約語のリストをご確認ください。
  3. アプリケーションのインストゥルメンテーション、APIの照会、またはその他の方法でイベントのJSONを生成します
  4. POSTリクエストでcURLを使用して、圧縮されたJSONペイロード(例:gzip もしくは deflate)をHTTPSエンドポイントに送信します。
  5. 推奨事項NRQLアラート条件をセットアップして、パーシングエラーの発生時に通知が送られるようにします。

このメソッドでは、イベントがお客様のアカウントに直接送信され、Insights UIもしくはQuery APIによってアクセス可能となります。

Event API では、カスタムイベントで使用できるサイズ、速度、文字を制限しています。他のInsightsイベント同様、作成後のカスタムイベントの更新や削除はできません。カスタムイベントで問題を経験している場合は、トラブルシューティング手順に従うか、新規カスタムイベントを作成してください。

Event APIのInsertキーの登録

Event APIのInsertキーを登録するには、Insights UIへのアクセス権ならびに正しい権限(所有者 (オーナー)管理者、もしくはアドオンマネージャー)を有している必要があります。

Event APIのInsertキーは、アカウント向けに生成されます。特定のユーザーとの関連はありません。このアカウント内のユーザーで、Insertキーへのアクセス権を有する人物であれば、Event APIを使用してイベントを追加できます。

有料のInsightsサブスクリプションがある場合は、一つのInsertキーで複数のイベントタイプを送信できます。ただし、安全性を確保するため、異なるアプリケーションや異なるデータソースには別々のInsertキーを使用してください。

Event APIのInsertキーを登録するには:

  1. insights.newrelic.com > Manage data > API keysを開きます。
  2. Insertキー見出しの隣りから、マークを選択します。
  3. キーに関する簡単な説明を入力します(所有者 (オーナー)、チーム、目的、データソース等)。
  4. Save your notesを選択します。

Insertキー ページには、該当キーに関するイベントデータを挿入するために必要なcURLコマンド一覧が表示されています。

安全上の理由から、APIを使用したInsertキーの変更や読み出しはできません。Insertキーの変更・読み出しには、New Relic UIを使用してください。

JSON書式

Event APIは、ペイロードに含まれた属性に関する特定の形式を受け入れます。フロートもしくは文字列の値のみが許容されます。

JSON書式のガイドライン

Insightsカスタムイベント向け属性を定義する際は、以下のJSON形式ガイドラインに従ってください。

属性 JSON書式のガイドライン
eventType 必須:イベントの名前。
フロートおよび文字列の値。

フロート値の形式:"label":value

文字列値の形式:"label":"value"

データタイプ Insightsは、キー/値ペアのみを受け付けており、マップ/オブジェクトや配列には対応していません。このAPIは、文字列と数値(整数または浮動小数)に対応しています。詳細については、 データ要件をご覧ください。
文字列中の数字

パフォーマンス上の理由から、Insightsは送信された値をキャストしません。たとえば、Insightは123を数値として、"123"を文字列として扱います。

Insightsが保存できるのは、最大で64ビットまでです。64ビットを超える数値は、切り捨てられます。

日付 日付情報を含む属性については、InsightsのManage data > Formatterの書式化されていないUnixタイムスタンプを使用してください。Unixエポックへの相対的な秒数かミリ秒数で日付属性を定義できます。
タイム

特に指定がない限り、送信されたイベントのタイムスタンプはそのイベントがNew Relicに送信された時間となります。イベントに異なる時間を指定するには、timestamp属性を使用してください。タイムスタンプは、New Relicにイベントが送信されてから24時間以内の64ビットの整数値でなくてはいけません。

JSONの例

これは、Insightsに送信するJSONデータセットの典型的な例を示したものです。このコールは、2つの PurchaseタイプのイベントをJSON配列として送信します。JSON配列を使用することで、単一のHTTPコールで複数のイベントを追加できます。

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

JSONを生成する際は、各属性が 適切に書式化されていることを確認してください。

上限値および文字の制限

Event APIに送信されたイベントには、以下のサイズおよび速度制限が適用されます:

  • ペイロードの合計サイズ:POSTあたり最大1MB。圧縮の使用を強く推奨します。
  • イベントあたりの属性数:最大255
  • 属性名の長さ:255文字
  • 属性値の長さ:最大長4KB
  • Event APIに送信される1分あたりのHTTPリクエスト数には、速度制限があります。

特定の属性には、追加の制限があります:

  • accountId:予約済みの属性名です。この名前が含まれている場合は、取り込み中に破棄されます。
  • appId:値は整数でなくてはいけません。整数ではない場合、属性名と値は取り込み中に破棄されます。
  • eventType:これは、英数字、_(アンダースコア)、:(コロン)の組み合わせにすることができます。コロンの組み合わせが可能です。
  • timestamp:Unixエポックのタイムスタンプでなければなりません。タイムスタンプは、秒数かミリ秒数で定義できます。

カスタムイベントの送信

Event APIに送信されるデータは、圧縮されたJSON形式をシンプルなHTTPS POSTリクエストで使用したものです。Insights UIのInsertキー ページでは、テンプレートとして使用できるサンプルのcURLクエリが自動的に生成されます。この例ではgzipを使用していますが、deflateでも可能です。

gzip -c example_events.json | curl -X POST -H "Content-Type: application/json" -H "X-Insert-Key: YOUR_KEY_HERE" -H "Content-Encoding: gzip" https://insights-collector.newrelic.com/v1/accounts/YOUR_ACCOUNT_ID/events --data-binary @-

必ず、全てのペイロードを圧縮しましょう。こうすることで、Insightsに送信できるデータの容量が増え、パーシング中のリソース節約になります。

HTTPリクエストを生成する際は、リクエストが適切に書式化されていることを確認してください。これには、以下の点が含まれます:

  • X-Insert-Keyに正しいInsertキーが含まれている。
  • Content-Typeapplication/jsonである。
  • リクエストはPOSTのみを使用している。APIは、PUTおよびGETリクエストを受け入れません。

APIはHTTP/1.1の持続的接続に対応しています。これは、イベントの負荷が非常に高い場合にクライアントサイドパフォーマンスを管理する上で役立ちます。

リクエストとレスポンスの確認またはトラブルシューティング

Event APIは、リクエストを処理するにあたって2段階のプロセスを踏みます:

  1. Event APIは、ヘッダーおよびペイロードのサイズの妥当性に基づき、リクエストを同期的に承認もしくは拒否します。
  2. Event APIは、成功したHTTPレスポンスがクライアントに提供された後で、非同期的にペイロードをパースします。これは、データの欠損もしくは不正な形式のデータによるエラーを生成する場合があります。これらは、送信エラーもしくはパーシングエラーとして分類されます。

送信に成功すると、ペイロード内に存在しうるデータエラーに関わらず、必ずレスポンスが200となります。このレスポンスに含まれるuuidは、各リクエスト向けに作成されるユニークIDになります。uuid は、リクエストに関して作成されたエラーイベントにも表示されます。

その他の予想される問題:

  • 10秒間のタイムアウト:10秒を超えるAPIコールはタイムアウトします。
  • 大きなペイロード:100 KBを超えるペイロードではレスポンスタイムが長くなる可能性があります。

推奨事項:成功メッセージの確認に加え、Insights Dataエクスプローラーを使用することで、イベントが適切にレポートされていることを確認し、クエリを生成できます。

成功レスポンスコード
成功メッセージ コメント
200
{"success":true,"uuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}
サブミッションエラー

送信エラーのあるペイロードは処理された後で、HTTPレスポンスコードを通じて送信者に返されます。

ペイロード送信エラーのトラブルシューティングに関しては、以下のHTTPレスポンスコードを参照してください。

サブミッションエラー トラブルシューティング
400

コンテンツの長さが不足しているか無効:空のリクエストを処理できません。

403

APIキーが不足しているか無効:Insertキーが無効であるか、アカウントにInsightsへのアクセス権限がありません。有効なInsertキーを登録してください。

408

リクエストがタイムアウトになりました:リクエストが長くかかりすぎるため、処理できません。

413

コンテンツが大きすぎます:リクエストが大きすぎるため、処理できません。トラブルシューティングの際は、上限値および文字の制限をご覧ください。

415

コンテンツタイプが無効です:application/JSONにする必要があります。Event APIは、multipart/related以外のすべてのContent Typeを受け付けており、それをJSONにパースできることを想定しています。

429

レート制限のため、リクエストが多すぎます。

503

一時的にサービスを利用できません:リクエストを再試行する

パーシングエラー

パーシングエラーは、以下の場合に発生します:

  • ペイロード内でイベントが送信されたものの、データが不足しているか上限を超えています。New Relicは、ペイロードから個別のイベントをドロップし、NrIntegrationErrorイベントを生成して、残りを処理します。
  • JSONペイロードには、不正な形式もしくは必須データ不足のJSONが含まれます。

パーシングエラーのあるペイロードは、送信が成功したことを示す200レスポンスを受信します。パーシングエラーを解決するため、NrIntegrationErrorイベントタイプ内で新規イベントが作成されます。全てのパーシングエラーは、Insights内のNRQLクエリが原因となります。New Relicでは、ドロップイベント関連のエラーメッセージに、メッセージの一環としてドロップされたイベント数が含まれます。

パーシングエラーのリクエストをトラブルシューティングするには、以下のHTTPレスポンスコードを参照してください。

パーシングエラー トラブルシューティング
属性appIdが整数でないため、Xのイベントを拒否

appId属性は、十進数もしくは文字列などの非整数値。

eventTypeは以下の文字を含むことができないため、Xのイベントを拒否:[., \]

eventType属性に、ピリオドやバックスラッシュなどの無効な文字が含まれている。

属性に属性名がないため、Xのイベントを拒否

属性名がNULLもしくは空の文字列。

属性名が最大文字数を超えたため、Xのイベントを拒否

属性名が255文字を超えている。

属性名が最大文字数を超えたため、Xのイベントを拒否

属性値が4KBを超えている。

イベントが属性数の上限を超えたため、Xのイベントを拒否

イベントの属性が255を超えている。

必須属性eventTypeが不足しているため、Xのイベントを拒否

カスタムイベントには eventType属性が必須。

JSONペイロードのパーシングエラー

形式上の問題もしくは破損したデータの影響で、JSONリクエストのパーシングエラーが発生。

NrIntegrationErrorによるクエリとアラート

NrIntegrationErrorイベントでは、ご利用のNew Relicアカウントに送信されるカスタムデータをクエリしてアラートを設定できます。推奨事項:New Relic Alertsからパーシングエラーに関する通知を受け取るには、NrIntegrationError向けにNRQL条件を作成します。以下のNRQLクエリの例を使用してください:

SELECT message FROM NrIntegrationError WHERE newRelicFeature = 'Event API' AND category = 'EventApiException'
NrIntegrationError属性 トラブルシューティング
timestamp リクエストを受け取った際のタイムスタンプ。timestamp属性は、書式なしのUnixタイムスタンプを使用します。Unixエポックへの相対的な秒数かミリ秒数でタイムスタンプを定義できます。
newRelicFeature エラーを経験している機能の名前。全てのカスタムイベントのパーシングエラーに関して、これはEvent APIになります。
apiKeyPrefix エラーを生成したリクエストで使用した、Insert APIキーの最初の6文字。
requestId エラーを生成したリクエストのAPIが返したuuid
Category エラーのカテゴリー。カスタムイベントの場合、これはEventApiExceptionになります。
Message エラーメッセージの内容。
Name エラーの名前。カスタムイベントの場合、これは常にEventValidationExceptionになります。

HTTPリクエストの上限

Event APIのレート制限は、1分あたりHTTPリクエスト100,000件(POST)となっています。(これは1分あたりのイベント数制限ではなく、1分あたりのPOST数のみとなる点に注意してください。)

こうした制限があることで、当社のマルチテナントプラットフォーム全体のアカウントにおける大量のトラフィック急増が、お客様へのサービスのパフォーマンスにネガティブに作用しないようにできます。

1分間の時間枠においてAPI使用状況が100k POSTを超えた場合、残りの1分間の時間枠における以後のAPIリクエストは、429のレスポンスコードによって拒否されます。1分間の時間枠の最後には、カウンターがリセットされてトラフィックが再開されます。

この制限は、通常の状況では達するべきでない上限閾値を示すものです。レスポンス数が429よりも多い場合、APIの使用頻度を減らすことを検討しましょう。近い将来、通常よりも高いアクティビティレベルが予想されており、それに備えたい場合は、テクニカルサポートに問い合わせてください

その他のヘルプ

推奨する詳細情報: