Event APIを使用してカスタムイベントをレポートする

New RelicのイベントAPIは、 カスタムイベントをNew Relicにレポートする1つの方法です。イベントAPIでは、POSTコマンドを使用してカスタムイベントデータをNew Relicアカウントに送信できます。これらのイベントはその後、NRQLを使用してクエリとチャート化が可能です。

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

関連コンテンツ:

基本ワークフロー

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

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

  1. Insert APIキーを登録してください。
  2. カスタムイベントまたは属性を作成する前に、New RelicのNRQLが使用する予約語のリストをご確認ください。
  3. アプリケーションのインストゥルメンテーション、APIの照会、またはその他の方法でイベントのJSONを生成します
  4. Submit a compressed JSON payload (for example, gzip or deflate) to the HTTPS endpoint using curl in a POST request.
  5. 推奨事項NRQLアラート条件をセットアップして、パーシングエラーの発生時に通知が送られるようにします。

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

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

Insert APIキーの登録

Insert APIキーを登録するには、正しいユーザー権限が必要です。

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

単一のInsert APIキーの下で、複数のイベントタイプを送信します。ただし、安全性を確保するため、異なるアプリケーションやデータソースには別々のキーを使用してください。

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

  1. From one.newrelic.com, click the account dropdown and then click Account settings.
  2. Click API keys. On the next page, click Insights API keys.
  3. Insertキー見出しの隣りから、マークを選択し、指示に従います。

The Insert key page lists the curl command necessary to add event data for the key.

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

JSON書式

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

JSON書式のガイドライン

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

属性 JSON書式のガイドライン
eventType 必須:イベントの名前。
浮動小数点および文字列の値。

浮動小数点数の形式:"label":value

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

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

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

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

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

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

JSONの例

APIとともに送信するための一般的な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文字
  • 属性値の長さ:最大 4096 文字
  • Event APIに送信される1分あたりのHTTPリクエスト数には、速度制限があります。

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

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

カスタムイベントの送信

Event APIに送信されるデータは、圧縮されたJSON形式をシンプルなHTTPS POSTリクエストで使用したものです。The Insert key page in the Insights UI automatically generates a sample curl query for you to use as a template. この例ではgzipを使用していますが、deflateでも可能です。

Linux/bashの例
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 @-
Windows/PowerShellの例
$accountId = "YOUR_ACCOUNT_ID"
$insertkey = "YOUR_KEY_HERE"
# Replace with your custom event for the body
$body = '[{"eventType": "powershell", "account": 4, "amount": 123, "fileLocation": "c:\\temp2", "zipped": "true" }]'

$headers = @{} 
$headers.Add("X-Insert-Key", "$insertkey") 
$headers.Add("Content-Encoding", "gzip")


$encoding = [System.Text.Encoding]::UTF8
$enc_data = $encoding.GetBytes($body)

$output = [System.IO.MemoryStream]::new()
$gzipStream = New-Object System.IO.Compression.GzipStream $output, ([IO.Compression.CompressionMode]::Compress)

$gzipStream.Write($enc_data, 0, $enc_data.Length)
$gzipStream.Close()
$gzipBody = $output.ToArray()

Invoke-WebRequest -Headers $headers -Method Post -Body $gzipBody  "https://insights-collector.newrelic.com/v1/accounts/$accountId/events"

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

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

  • X-Insert-Keyに正しいInsert APIキーが含まれている。
  • 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を超えるペイロードではレスポンスタイムが長くなる可能性があります。

推奨事項:In addition to checking for a success message, use the Insights data explorer to ensure your events are reporting correctly and to generate queries.

成功レスポンスコード
成功メッセージ コメント
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イベントタイプが作成されます。全てのパーシングエラーはNRQLクエリが原因となります。New Relicでは、ドロップイベント関連のエラーメッセージに、メッセージの一環としてドロップされたイベント数が含まれます。

パーシングエラーのリクエストをトラブルシューティングするには、これらのエラーメッセージを参照してください。

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

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

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

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

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

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

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

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

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

属性値が 4096 文字を超えました。

イベントが属性数の上限を超えたため、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になります。
eventTypeSample 可能な場合、エラーを生成したイベントタイプの1つ。

データを検索する

イベントAPIを通じて(またこのAPIを使用するインテグレーションから)送信されたデータを検索するには、データのクエリを行えます。たとえば、NRQLを使用してカスタムイベントのクエリを行うには、次を実行します:

SELECT * FROM YOUR_CUSTOM_EVENT 

クエリの方法の詳細については、クエリデータをご覧ください。

HTTPリクエストの上限

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

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

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

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

その他のヘルプ

さらに支援が必要な場合は、これらのサポートと学習リソースを確認してください: