• /
  • Log in
  • Free account

New Relic Insights best practices guide


As of April 12, 2021, we are upgrading Insights to an improved web and mobile experience! All of your Insights URLs will be redirected automatically to the corresponding dashboards in New Relic One. For more details about this migration and how you can easily plan for this transition, see our Explorers Hub post.

As software systems grow more complex, the teams building the next generation of websites, apps, and services need tools that can provide end-to-end visibility across the entire stack. New Relic provides these tools—offering the features (such as sub-second query responses on real-time data, dashboards with powerful charting, and flexible alerts) that are essential to building great products.

Bundled into all New Relic solutions, Insights enables users to unlock the full power of the un-aggregated, highly dimensional event data collected by New Relic agents. By applying the tips and best practices detailed here, you can use New Relic Insights to build better performance into your systems with every release.

1. Explore your data


We have an improved way to query and create custom charts: New Relic One. For tips on switching from Insights to New Relic One, see this transition guide.

The Insights data explorer offers rich, full-text search across thousands of events and metrics collected by New Relic agents on your applications and hosts. Use it to explore and chart not just the default available data types but also any custom events and metrics you’ve added.

For example, if you were to use custom metrics to track messages sent and received on a Kafka queue, you could easily find and add those metrics to a dashboard alongside error rate or throughput trends.

From within the metric explorer, you can change the scope of metrics using wildcards, facet your metrics by application host, and expose an API call for the metric via a single click.

How to do it (Event explorer)

Here's how to use the Insights event data explorer:

  1. Go to insights.newrelic.com and select Data explorer > Events.

  2. Select a data type to explore.

  3. Review the attribute names and values shown for the data matching your view.

  4. Select attributes to group by and plot.

    • On the NRQL-generated query, click Run.
    • Configure the chart options as needed.
    • To add individual charts to a dashboard: Give the chart a meaningful title to identify it in a dashboard. Select Add to a dashboard.

How to do it (Metric explorer)

Here's how to use the Insights metric data explorer:

  1. Go to insights.newrelic.com and select Data explorer > Metrics.
  2. Select the entity or application your metrics report under. (To select a metric for your chart, browse the top metrics or search for a metric name.)
  3. View metric charts as you select them.
  4. Configure the chart options.
  5. Optional: To visit the API Explorer (which is preset to the selected metric and time range), select Explore API.
  6. To add individual charts to a dashboard, select Add to dashboard.
  7. Give each chart a meaningful title to identify it on the target dashboard.

2. Try out NRQL queries

Once you’ve explored some of the taxonomy of your data via data explorer, it’s time to start asking some direct questions of your data. You can do this via NRQL: a query language for making calls against our database. If you know SQL, you will already be familiar with a lot of NRQL syntax. And if you don’t know SQL, no worries: We’ll use example queries to get you up and running quickly.

At its core, NRQL enables you to query data collected from your application and transform it into dynamic charts. You can then use that data to better understand how your application is used.

For example, during incident response, you can test multiple hypotheses by asking and answering multiple questions in rapid succession—down to the individual user or end point (thanks to the un-aggregated, highly dimensional nature of New Relic data).

How to do it

Use the command-line query tool that appears at the top of your dashboards and on the Query history page to build commands with SQL-style syntax. As you type, the auto-completion feature suggests attributes and flags syntax errors with a red underline. (For more information about NRQL syntax, see Introduction to NRQL and NRQL reference.

Here are some example NRQL queries to show you the art of the possible:

  • Out-of-the-box performance:

    • What is the distribution of response times for my app?

      SELECT histogram(duration, width: 2, buckets: 20) FROM Transaction WHERE appName = YOUR_APP_NAME SINCE 1 day ago
    • What percent of time is spent in the application processing the request (outside of database processing)?

      SELECT (1-(average(duration)-average(databaseDuration))/average(duration))*100 AS '% of time in DB' FROM Transaction FACET name WHERE appName = YOUR_APP_NAME
  • Lightweight custom instrumentation to drill down to an individual user:

    • SELECT count(*) FROM MobileCrash WHERE `authentication_email` = ‘exampleuser@newrelic.com'
    • Authentication_email is a custom attribute that’s been added to the default MobileCrash event type with a single line of code. (Find out more here.)

See more examples:

3. Pin charts from other New Relic products

Now that you’ve explored your data and asked some questions, it’s time to learn how Insights can be integrated with charts from other New Relic products. Using the add-to-Insights feature, you can pin any New Relic chart to an Insights dashboard.

How to do it

  1. Mouse over the chart.
  2. Click the Add to an Insights Dashboard button.
  3. From the Copy chart dialog box:
    • Select Copy to an existing dashboard (default) or Copy to a new dashboard.
    • Edit the chart name as needed (maximum length: 255 characters).
    • Click Copy. (Note: You can switch accounts from this dialog box to copy to different dashboards across accounts. You can also click the dashboard name in the green success bar to go the dashboard to which you added the chart.)

4. Create dashboard notes

To make your dashboard more usable across your entire organization, use the dashboard notes feature to add context to any dashboard. Have a chart you’d like to describe for others? Have important links that go hand-in-hand with the dashboard (for example a runbook)? Dashboard notes allow you to add arbitrary text and images to your dashboard.

Add notes to dashboards to record or share custom information about the dashboard. Because these notes use markdown syntax, it is easy to add elements such as headings, images, links, and so on.

How to do it

  • At the top of the dashboard, select Add Dashboard note.

5. Designate dashboards as favorites

Get fast access to key dashboards by designating them as favorites.

How to do it:

  • To make a dashboard a favorite, click the star icon. (Favorite dashboards appear at the top of the dashboards list.)
  • To remove a dashboard from your favorites, click the star icon again.

5. Apply a filter to a dashboard

You can easily drill down into specifics about your data in Insights. All you have to do to change the data presented is input text into a search box. For example, anyone can visit a dashboard and input a user's email address to access data un-aggregated for that user.

How to do it:

  1. On the dashboard, select Edit.
  2. Then select Filter disabled or click the gear icon.
  3. Select Enable filter.
  4. From the Event types drop-down menu, select one or more data types.
  5. From the Select attribute drop-down menu, select one or more attributes to restrict filtering to specific attributes.
  6. Select Filter enabled or click the blue gear icon again to close the Filter menu.
  7. To save your changes to the dashboard, select Done editing.

6. Build a data app

Do you want to present a bunch of dashboards as a whole? Are you thinking about sharing information beyond your DevOps teams? Data apps can help you do so.

Designed to let users create self-service analytics reports that even non-technical users can employ to answer questions about performance, customers, feature usage, and more, data apps let business users click through preset drill-downs and modify their filters in real time via basic searches. As collections of linked dashboards that create curated, application-like experiences, data apps work on any attributes available in Insights.

How to do it:

  1. Go to insights.newrelic.com > Data apps > Create a data app.
  2. Specify an Icon, Title, URL, Description, and Permissions for your app.
  3. Select Create to save your new data app.
  4. After creating your data app, Insights automatically redirects you to a new dashboard. You can add widgets to this dashboard using standard NRQL queries.
  5. You can also create additional dashboards by selecting + Add from the data app navigation bar, or by copying an existing dashboard into your data app:
    • From your data app dashboard, select Edit, then select Configure data app.
    • From the Copy dropdown menu, choose a dashboard. (Dashboard copies are independent of the original dashboard—meaning changes to the original dashboard do not affect the copy, and editing or deleting the copied dashboard does not affect the original.)

Learn more about data apps.

7. Link facets across dashboards within a data app

Facet linking is a powerful way to build dashboards to tell a deep story around specific filters. For example, you can use the FACET clause in NRQL to break out your data by any string attribute. Use the LIMIT clause to specify how many facets appear (the default is 10). For more complex grouping, use FACET CASES.

By using FACET linking, a user can jump to details of an individual company on a prebuilt dashboard showing specifics for that company.

How to do it:

  1. Go to insights.newrelic.com > Data apps > (select a data app).
  2. Select the dashboard containing the widget you want to link from; then select Edit.
  3. From the widget you want to link, select the link icon.
  4. Select the target dashboard from the list.

8. Add a custom attribute and/or event via a New Relic agent

All New Relic agents report some event data by default, out of the box. For example, each time a Mobile event occurs, more than 35 attributes are added, providing a wealth of ways to slice and dice your data. This allows you to troubleshoot faster, understand better, and focus on creating value rather than putting out fires.

Eventually, however, you will probably want to add custom attributes to your event data. For example: you might want to add a unique user ID attribute that will let you see performance data on an individual user. With just a few lines of code, you can add custom attributes to your event data to enhance your ability to dashboard and filter your data along with other methods depending on the language.

Since the approach you use will be specific to the agent you’re employing, we’ve provided a couple of examples below. Please view the New Relic docs for specifics on the agent you’re using.

How to do it (for Java via agent API; you can also use an XML approach)

  1. To collect custom attributes via API, call the relevant methods.
  2. For each method you want to record an attribute, call addCustomParameter.
  3. Optional: Include or exclude certain attributes with attributes.include and attributes.exclude. For example, to record a variable named userId, include the following code in the parent method: NewRelic.addCustomParameter("userId", userId).

How to do it (for Agent API via Java APM agent)

  • Custom event collection is enabled by default in Java agent version 3.13.0 or higher. To send custom events, simply call the relevant API. For example:
    • Map<String, Object> eventAttributes = new HashMap<String, Object>(); NewRelic.getAgent().getInsights().recordCustomEvent('MyCustomEvent', eventAttributes);
  • In the above example, the first argument defines the name of your event type, and the second argument is a map with the attributes for your custom event.
  • Ensure you limit the number of unique event type names you create, and do not generate these names dynamically. For restrictions on event type names, see Limits and restricted characters and Reserved words.
  • You can change the maximum number of events recorded by the Java agent via a configuration parameter in newrelic.yml: Simply add custom_insights_events.max_samples_stored: to your configuration file.
  • Specify the maximum number of events to record per minute as an integer. For example, if you want to send less than the default of 10,000 events, use the following: custom_insights_events.max_samples_stored: 5000
  • To disable custom events, add custom_insights_events.enabled: false to newrelic.yml.

9. Add a custom event Insights end point

You can also enhance the information you report about your applications and systems by creating a custom event—via either a New Relic agent API or the Event API. If you chose the latter, you can send information from your system without adding a New Relic agent to it. You get all the benefits of our agent’s deep instrumentation in other parts of your stack in places where we don’t have an agent or you don’t want to add one. Keep in mind that Insights only supports event insertion via POST. Follow the instructions below to start reporting a new event type.

How to do it:

  1. Go to the Manage data section of Insights.
  2. Click the API Keys tab.
  3. Register an Event API Insert key.
  4. Generate JSON for the event by instrumenting your application, querying an API, or some other method.
  5. Submit the JSON to the Insights HTTPS end point using cURL in a POST request. (More info)

Be sure to check out New Relic API Explorer

By taking advantage of New Relic API Explorer (available at https://api.newrelic.com), Admin users and those with the API Key can:

  • Browse available API end points
  • Interact with the API within a user interface (the API Explorer)
  • View a live source of documentation
  • Obtain cURL commands for API actions
  • Share configured API calls with colleagues by copy and pasting API Explorer URLs.

For more about reporting custom events, see Custom events.

Want more user tips?

See our other product best-practice docs (found in New Relic docs) for more in-depth best practices on using Insights in conjunction with those products.

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.