Send custom events with our Event API

The Event API lets you send custom event data to New Relic. These events can then be queried and charted.

Want to try out our Event API? Create a New Relic account for free! No credit card required.

Related content:

• Learn about all options for reporting custom events.
• For how to add attributes to existing events, see Add custom attributes.

Why use the Event API?

Our Event API is one option for reporting custom data. Another option is reporting custom attributes. For an overview of why you'd use the Event API versus other options, see Custom events and attributes.

Requirements

For Event API limits and restricted attributes, see Limits.

Ensure outbound connectivity on TCP port 443 is allowed to the CIDR range that matches your region. The preferred configuration method is to use the DNS name insights-collector.newrelic.com or insights-collector.eu01.nr-data.net.

Example of submitting and querying a custom event

Here's an example of the Event API in action:

# 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

How to use the Event API

The Event API is an asynchronous endpoint. This allows you to send a very large volume of POSTS, reliably, with very low response latency.

To send a custom event to a New Relic account:

1. Get a license key for the account you want to report data to.
2. Before creating custom events or attributes, review our list of reserved terms used by NRQL.
3. Generate JSON for the event by instrumenting your application, querying an API, or some other method.
4. Submit a compressed JSON payload (for example, gzip or deflate) to the HTTPS endpoint using curl in a POST request.
5. Recommendation: Set up NRQL alert conditions to notify you when parsing errors occur.

The Event API limits the size, rate, and characters allowed in custom events. Also, like other data available in NRQL, custom events cannot be updated or deleted after they're created. If you have problems with your custom event, follow the troubleshooting procedures or create a new custom event.

Format the JSON

The Event API accepts specific formats for attributes included in the payload. Only float or string values are allowed.

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

Submit the custom event

Data submitted to the Event API uses a compressed JSON format in a simple HTTPS POST request. This example uses gzip, but you can also use 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"

Before generating your HTTP request, make sure it is properly formatted, including:

• The Api-Key contains the correct license key.
• The Content-Type is application/json.
• The request uses POST only. The API does not accept PUT and GET requests.

The API supports HTTP/1.1 persistent connections. This is helpful to manage client-side performance under heavy event loads.

Verify or troubleshoot request response

The Event API follows a two-step process to process requests:

1. The Event API synchronously acknowledges or rejects the request based on validation of the headers and payload size.
2. The Event API asynchronously parses the payload after a successful HTTP response is provided to the client. This may generate an error due to missing or malformed data. These are classified as submission errors or parsing errors.

All successful submissions receive a 200 response, regardless of any data errors that may exist within the payload. The response includes a uuid, which is a unique ID created for each request. The uuid also appears in any error events created for the request.

Other potential issues:

• 10-second timeout: API calls exceeding 10 seconds will time out.
• Large payloads: Payloads exceeding 100 KB may see increased response times.

Recommendation:In addition to checking for a success message, create a NRQL query of your data to verify it's available.

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

Query and alert with NrIntegrationError

The NrIntegrationError event allows you to query and set alerts on custom data being sent to your New Relic account. Recommendation: To get alerts for parsing errors, create a NRQL alert condition for NrIntegrationError. Use this example NRQL query:

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

Find your data

To find data sent via the Event API (and from integrations that use this API), you can query it. For example, to query a custom event using NRQL, you would run:

SELECT * FROM YOUR_CUSTOM_EVENT

For more on how to query, see Query data.

Limit on HTTP requests

The Event API has a rate limit of 100,000 HTTP requests (POSTs) per minute, per account. (Note that this is not a limit on the number of events per minute; only on the number of POSTs per minute.)

This limit helps ensure that large traffic spikes in accounts across our multi-tenant platform do not negatively affect how the service performs for you.

If your API usage exceeds 100k POSTs in a 1-minute window, we will reject subsequent API requests with a 429 response code for the remainder of the 1-minute window. At the end of the 1-minute window, the counter will be reset and allow traffic to resume.

This limit is intended to be an upper threshold that you shouldn't hit under normal scenarios. If you have a high number of 429 responses, consider using the API less. If you are expecting a higher-than-normal activity level in the near future and want to prepare for that, contact technical support.