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

イベントAPIでは、カスタムイベントデータをNew Relicに送信できます。その後、これらのイベントをクエリしてチャート化できます。

当社のイベントAPIをお試しになりますか？New Relicアカウントの作成は無料です。クレジットカードは不要です。

関連コンテンツ：

• カスタムイベントのレポートについてのすべてのオプションの詳細を調べます。
• 既存イベントに属性を追加する方法については、カスタムアトリビュートを追加するを参照してください。

イベントAPIを使用する理由

当社のイベントAPIは、カスタムデータをレポートするための1つのオプションです。もう1つのオプションとして、カスタムアトリビュートのレポートがあります。他のオプションに対してイベントAPIを使用する理由の概要については、カスタムイベントと属性を参照してください。

要件

イベントAPIの限界および制限された属性については、制限を参照してください。

TCPポート443のアウトバウンド接続が、地域に一致するCIDR範囲に使用できることを確認します。推奨される設定方法は、DNS名insights-collector.newrelic.comまたはinsights-collector.eu01.nr-data.netを使用することです。

カスタムイベントの送信とクエリの例

以下は、イベントAPIの動作例です：

# Hook into the runtime 'at_exit' event
at_exit do
  # Name the custom event
  payload = { 'eventType' => 'CLIRun' }

  # Check to see if the process is exiting due to an error
  if $!.nil? || $!.is_a?(SystemExit) && $!.success?
    payload[:status] = 0
  else
    # Gather any known errors
    errors = ""
    (Thread.current[:errors] ||= []).each do |err|
      errors += "#{err}\n"
    end
    payload[:errors] = errors
  end

  # Send the errors to New Relic as a custom event
  insights_url = URI.parse("https://insights-collector.newrelic.com/v1/accounts/YOUR_ACCOUNT_ID/events")
  headers = { "Api-Key" => "YOUR_LICENSE_KEY", "content-type" => "application/json" }

  http = Net::HTTP.new(insights_url.host, insights_url.port)
  http.use_ssl = true
  request = Net::HTTP::Post.new(insights_url.request_uri, headers)
  request.body = payload.to_json

  puts "Sending run summary to New Relic: #{payload.to_json}"
  begin
    response = http.request(request)
    puts "Response from New Relic: #{response.body}"
  rescue Exception => e
    puts "There was an error posting to New Relic. Error: #{e.inspect}"
  end
end

SELECT count(*) FROM CLIRun FACET errors SINCE 1 week ago

イベントAPIの使用方法

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

New Relicアカウントにカスタムイベントを送信する場合は、以下の手順に従います。

1. データをレポートするアカウントのライセンスキーを取得します。
2. カスタムイベントまたは属性を作成する前に、当社のNRQLが使用する予約語のリストを確認します。
3. アプリケーションのインストゥルメンテーション、APIの照会、またはその他の方法でイベントのJSONを生成します。
4. POSTリクエストでcurlを使用し、圧縮されたJSONペイロード（例：gzipまたはdeflate）をHTTPSエンドポイントに送信します。
5. 推奨事項：NRQLアラート条件を設定し、構文解析エラー発生時に通知します。

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

JSONのフォーマット化

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

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

カスタムイベントの送信

イベント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段階のプロセスを踏みます。

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

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

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

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

推奨事項：成功メッセージの確認に加えて、データのNRQLクエリを作成して、データが利用可能であることを確認します。

{ "success": true, "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }

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

NrIntegrationErrorイベントでは、 New Relicアカウントに送信されるカスタムデータをクエリしてアラートを設定できます。推奨事項：解析エラーのアラートを取得するには、 NrIntegrationErrorのNRQLアラート条件を作成します。以下のNRQLクエリ例を使用します。

SELECT message FROM NrIntegrationError WHERE newRelicFeature = 'Event API' AND category = 'EventApiException'

データを検索する

イベント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の使用頻度を減らすことを検討します。近い将来、通常よりも高いアクティビティレベルが予想されており、それに備えたい場合は、テクニカルサポートに問い合わせてください。