Back to top icon

New Relic Developers

Get data in and out of New Relic

Extend our core data, add your own, or pull data out of our platform entirely.

Custom attributes

There are countless filters and pivots you may want to apply to your data. Custom attributes let you add your own metadata to any of our core events, so you can start seeing beyond your code and analyzing your business in-depth.

You can add a 'userid' custom attribute through the Agent API within the Java APM agent.

NewRelic.addCustomParameter("userid", userId);

Run a NRQL query that uses the 'userid' custom attribute.

-- Get a count of errors experienced by a single filtered userid faceted by date and error message
SELECT count(*) FROM TransactionError WHERE userid = '616e6472-6577-7340-7961-686f6f2e636f' FACET dateOf(timestamp), `error.message` SINCE 1 week ago

Once you have added a custom attribute like 'userid', you can use it to filter and facet your NRQL queries. 

Custom events

Where a custom attribute adds metadata to an existing event, a custom event creates an entirely new event type. Create custom events to define, visualize, and get alerts on additional data, just as you would with any data we provide from our core agents.  

Custom events can be inserted through the Agent APIs or directly via the Insights Insert API. The following example shows how to send a custom event named CLIRun that tracks when a command line tool written in Ruby has its process exit due to an exception.

# 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
    # Gather any known errors
    errors = ""
    (Thread.current[:errors] ||= []).each do |err|
      errors += "#{err}\n"
    payload[:errors] = errors

  # Send the errors to New Relic as a custom event
  insights_url = URI.parse("")
  headers = { "x-insert-key" => "YOUR_API_KEY", "content-type" => "application/json" }

  http =, insights_url.port)
  http.use_ssl = true
  request =, headers)
  request.body = payload.to_json

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

Here, a NRQL query retrieves information about the custom event, and the result can be added to a dashboard.

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

Build out your own agent to get deep visibility into highly customized, unique, or legacy systems.

Using the Infrastructure Integrations SDK, you can get data from specific entities into New Relic without having to worry about timings of harvest cycles. The following example shows a custom Apache Integration built atop the Infrastructure Integrations SDK.


Code snippet from the Apache integration's main method in Go.

func main() {
  log.Debug("Starting Apache integration")
  defer log.Debug("Apache integration exited")

  integration, err := sdk.NewIntegration(integrationName, integrationVersion, &args)

  if args.All || args.Inventory {
    log.Debug("Fetching data for '%s' integration", integrationName+"-inventory")

  if args.All || args.Metrics {
    log.Debug("Fetching data for '%s' integration", integrationName+"-metrics")
    ms := integration.NewMetricSet("ApacheSample")
    provider := &Status{
      CABundleDir:  args.CABundleDir,
      CABundleFile: args.CABundleFile,
      HTTPTimeout:  defaultHTTPTimeout,
    fatalIfErr(getMetricsData(provider, ms))

Fetch data from APIs

Whether you're running advanced analytics, enhancing an existing data workflow, or trying to do something novel with New Relic data, you can do it programmatically with our APIs.

To access data and use it outside of New Relic, use one of these APIs. 

Fetch metrics from the RESTv2 API.

curl -X GET '' \
     -H 'X-Api-KeyYOUR_API_KEY' -i \
     -G -d 'names[]=YOUR_METRIC_NAME' 

Fetch events from the Insights Query API.

curl -H "Accept: application/json" -H "X-Query-Key: YOUR_QUERY_KEY" \ 

Fetch events, including cloud integration data, from the New Relic GraphQL API.

  currentUser {
    currentAccount {
      nrdbQuery(nrql: "YOUR_NRQL_QUERY") {