New RelicのイベントAPIは、 カスタムイベントをNew Relicにレポートする1つの方法です。イベントAPIでは、POSTコマンドを使用してカスタムイベントデータをNew Relicアカウントに送信できます。これらのイベントはその後、NRQLを使用してクエリとチャート化できます。
当社のイベントAPIをお試しになりますか？New Relicアカウントの作成は無料です。クレジットカードは不要です。
関連コンテンツ：
要件
イベントAPIの限界および制限された属性については、制限を参照してください。
TCPポート443のアウトバウンド接続が、地域に一致するCIDR範囲に使用できることを確認します。推奨される設定方法は、DNS名insights-collector.newrelic.comまたはinsights-collector.eu01.nr-data.netを使用することです。
基本ワークフロー
イベントAPIは、非同期のエンドポイントです。このため、大容量のPOSTを、非常に低いレスポンスレイテンシで確実に送信できます。
New Relicアカウントにカスタムイベントを送信する場合は、以下の手順に従います。
- データをレポートするアカウントのライセンスキーを取得します。
- カスタムイベントまたは属性を作成する前に、New RelicのNRQLが使用する予約語のリストを確認します。
- アプリケーションのインストゥルメンテーション、APIの照会、またはその他の方法でイベントのJSONを生成します。
- POSTリクエストでcurlを使用し、圧縮されたJSONペイロード（例：
gzipまたはdeflate）をHTTPSエンドポイントに送信します。 - 推奨: NRQLアラート条件を設定し、構文解析エラー発生時に通知します。
このメソッドでは、イベントがアカウントに直接送信され、任意のNRQLインタフェースから、またはクエリAPIによってアクセスできるようになります。
イベントAPIでは、カスタムイベントで使用できるサイズ、速度、文字を制限しています。NRQLにおいて使用な他のイベント同様、作成後のカスタムイベントの更新や削除はできません。カスタムイベントに問題がある場合は、トラブルシューティング手順に従うか、または新規カスタムイベントを作成します。
ライセンスキーの取得
ライセンスキーが必要です。ライセンスキーは、特定のユーザーではなく、アカウントに関連付けられています。これは、そのキーにアクセスできるアカウント内の誰もがそのキーを使用できることを意味します。
同じライセンスキーを使用して、複数のイベントタイプを同じアカウントに送信することができます。ただし、安全性を確保するため、異なるアプリケーションやデータソースには別々のキーを使用してください。
JSONのフォーマット化
イベントAPIは、ペイロードに含まれる属性に対する特定の形式を受け入れます。浮動小数点または文字列値のみが許容されます。
カスタムイベント向け属性を定義する際は、以下のJSON形式ガイドラインに従います。
属性 | JSON書式のガイドライン |
|---|
eventType
| 必須: イベント名。 |
浮動小数点および文字列値。 | 浮動小数点数の形式： "label":value 文字列値の形式： "label":"value" |
データ型 | APIは、キー/値ペアのみを受け付けており、マップ/オブジェクトまたは配列値には対応していません。このAPIは、文字列と数値（整数または浮動小数点数）のデータ型に対応しています。詳細については、 データ要件を参照してください。 |
文字列中の数字 | パフォーマンス上の理由から、APIに送信された値をキャストしません。たとえば、123を数値として、"123"を文字列として扱います。 データベースが保存できるのは、最大で64ビットまでです。64ビットを超える数値は、切り捨てられます。 |
日付 | 日付情報を含む属性には、データフォーマッターの書式化されていないUnixタイムスタンプを使用します。Unixエポックからの相対的な秒数かミリ秒数で日付属性を定義できます。 |
時刻 | 特に指定がない限り、送信されたイベントのタイムスタンプはそのイベントがNew Relicに送信された時刻となります。イベントに異なる時間を指定するには、timestamp属性を使用してください。 |
APIとともに送信するための一般的なJSONデータセットの例を以下に示します。このコールは、2つの 購買タイプのイベントをJSON配列として送信します。JSON配列を使用することで、単一のHTTPコールで複数のイベントを追加できます。
JSONを生成する際は、各属性が適切に書式化されていることを確認してください。
イベントAPIを介して送信されるイベントには、以下のサイズと速度の制限が適用されます。
APIコールあたりの最大イベント数：
ペイロード合計サイズ: POSTあたり最大1MB(10^6バイト)。圧縮の使用を強く推奨します。
ペイロードは UTF-8 としてエンコードする必要があります。
イベントあたりの属性の最大数：255
属性名の最大長：255文字
属性値の最大長：4096文字
イベントAPIに送信される1分あたりのHTTPリクエスト数には、速度制限があります。
特定の属性には、追加の制限があります。
accountId：これは予約した属性名です。この名前が含まれている場合は、取り込み中に破棄されます。
entity.guid、entity.name、およびentity.type：これらの属性は、エンティティを識別するために内部で使用されます。メトリックデータポイントの属性セクションでこれらのキーとともに送信される値によって、UIのエンティティが見つからない、またはテレメトリが予期されるエンティティと関連していないなどの未定義の動作が発生する場合があります。詳細については、エンティティの合成を参照してください。
appId：値は整数である必要があります。整数ではない場合、属性名と値は取り込み中に破棄されます。
eventType：英数字、_（アンダースコア）、:（コロン）の組み合わせにすることができます。
timestamp：Unixエポックのタイムスタンプである必要があります。タイムスタンプは、秒数かミリ秒数で定義できます。
カスタムイベントの送信
イベントAPIに送信されるデータは、圧縮されたJSON形式をシンプルなHTTPS POSTリクエストで使用するものです。この例ではgzipを使用していますが、deflateでも可能です。
gzip -c example_events.json | curl -X POST -H "Content-Type: application/json"
-H "Api-Key: YOUR_LICENSE_KEY" -H "Content-Encoding: gzip"
https://insights-collector.newrelic.com/v1/accounts/YOUR_ACCOUNT_ID/events --data-binary @-
$accountId = "YOUR_ACCOUNT_ID"
$insertkey = "YOUR_LICENSE_KEY"
# Replace with your custom event for the body
$body = '[{"eventType": "powershell", "account": 4, "amount": 123, "fileLocation": "c:\\temp2", "zipped": "true" }]'
$headers = @{}
$headers.Add("Api-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リクエストを生成する前に、リクエストが適切に書式化されていることを確認してください。これには、以下が含まれます。
Api-Keyには正しいライセンスキーが含まれています。Content-Typeはapplication/jsonです。- リクエストはPOSTのみを使用している。APIは、PUTおよびGETリクエストを受け入れません。
APIはHTTP/1.1の持続的接続に対応しています。これは、イベントの負荷が非常に高い場合にクライアント側のパフォーマンスを管理する上で役立ちます。
リクエストとレスポンスの確認またはトラブルシューティング
イベントAPIは、リクエストを処理するにあたって2段階のプロセスを踏みます。
- イベントAPIは、ヘッダーおよびペイロードのサイズの妥当性に基づき、リクエストを同期的に応答または拒否します。
- イベントAPIは、成功したHTTPレスポンスがクライアントに提供された後で、非同期的にペイロードを構文解析します。これは、データの欠損もしくは不正な形式のデータによるエラーを生成する場合があります。これらは、送信エラーまたは構文解析エラーとして分類されます。
送信に成功すると、ペイロード内に存在しうるデータエラーに関わらず、すべてのレスポンスは200となります。このレスポンスに含まれるuuidは、各リクエスト向けに作成されるユニークIDになります。uuidは、リクエストに関して作成されたエラーイベントにも表示されます。
その他の予想される問題：
- 10秒を超えるAPIコールはタイムアウトします。
- 100 KBを超えるペイロードではレスポンスタイムが長くなる可能性があります。
推奨：成功メッセージの確認に加えて、データのNRQLクエリを作成して、データが利用可能であることを確認します。
成功メッセージ | コメント |
|---|
200 | {"success":true,"uuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}
|
送信エラーのあるペイロードは処理された後で、HTTPレスポンスコードで送信者に返されます。
ペイロード送信エラーのトラブルシューティングについては、以下のHTTPレスポンスコードを参照してください。
送信エラー | トラブルシューティング |
|---|
400 | 欠落または無効のコンテンツ長: 処理できない空のリクエスト。 |
403 | キーがないか、無効です：ライセンスキーが無効です。有効なライセンスキーを登録します。 |
408 | リクエストタイムアウト: 処理に時間がかかり過ぎたリクエスト。 |
413 | 大き過ぎるコンテンツ: 大き過ぎて処理できないリクエスト。トラブルシューティングの際は、 上限値および文字制限を参照します。 |
415 | 無効なコンテンツタイプ: Content-Typeはapplication/jsonにする必要があります。イベントAPIは、multipart/related以外のすべてのコンテンツタイプを受け付けており、それを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を超えている。 |
必須属性が不足しているため、Xイベントを拒否 eventType | カスタムイベントには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属性を使用すると、過去24時間以内で64ビット整数のUnixタイムスタンプを取得します。Unixエポックからの相対的な秒数かミリ秒数でタイムスタンプを定義できます。 タイムスタンプには小数点を使用しないでください。小数点を使用する場合、カスタムイベント作成時の属性がタイムスタンプのデフォルトになります。 |
newRelicFeature
| エラーが発生している機能の名前。すべてのカスタムイベントの構文解析エラーには、これはEvent APIになります。 |
apiKeyPrefix
| エラーを生成したリクエストで使用した、ライセンスキーの最初の6文字。 |
requestId
| エラーを生成したリクエストのAPIが返したuuid。 |
Category
| エラーのカテゴリー。カスタムイベントの場合、これはEventApiExceptionです。 |
Message
| エラーメッセージの内容。 |
Name
| エラーの名前。カスタムイベントの場合、これは常にEventValidationExceptionです。 |
eventTypeSample
| 使用可能な場合、エラーを生成したイベントタイプの1つ。 |
データを検索する
イベントAPIを通じて（またこのAPIを使用するインテグレーションから）送信されたデータを検索するには、データのクエリを行えます。たとえば、NRQLを使用してカスタムイベントのクエリを行うには、次を実行します。
SELECT * FROM YOUR_CUSTOM_EVENT
クエリ方法の詳細については、クエリデータを参照してください。
HTTPリクエストの制限
イベントAPIのレート制限は、アカウントあたり毎分HTTPリクエスト100,000件（POST）です。（これは1分あたりのイベント数制限ではなく、1分あたりのPOST数のみとなる点に注意してください。）
こうした制限があることで、当社のマルチテナントプラットフォーム全体のアカウントにおける大量のトラフィック急増が、サービスのパフォーマンスにネガティブに作用しないようにできます。
1分間の時間枠においてAPI使用状況が100k POSTを超えた場合、残りの1分間の時間枠における以後のAPIリクエストは、429のレスポンスコードによって拒否されます。1分間の時間枠の最後には、カウンターがリセットされてトラフィックが再開されます。
この制限は、通常の状況では達するべきでない上限閾値を示すものです。レスポンス数が429よりも多い場合、APIの使用頻度を減らすことを検討します。近い将来、通常よりも高いアクティビティレベルが予想されており、それに備えたい場合は、テクニカルサポートに問い合わせてください。