Skip to main content
Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor’s documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.
New Relic is a performance tracking and analytics tool that helps engineers gain visibility into their software. Integrating New Relic with Cortex allows you to:
  • Discover entities and track ownership
  • View SLO and monitoring information on entity pages in Cortex
  • Embed New Relic dashboards on entity pages in Cortex
  • Create Scorecards to drive alignment on projects involving New Relic metrics

​
How to configure New Relic with Cortex

​
Prerequisite

Before getting started:
  • As a full platform user in New Relic, create a New Relic user key.
    • New Relic user keys are linked to the account they were created from, so if this account is ever deleted, the integration with Cortex will stop working.

​
Configure the integration in Cortex

  1. In Cortex, navigate to the New Relic settings page:
    1. Click Integrations from the main nav. Search for and select New Relic.
  2. Click Add configuration.
  3. Configure the New Relic integration form:
    • Account alias: Enter a name for this account.
    • Personal key: Enter the user key you generated in New Relic.
    • Account ID: Enter the ID for the account that the user key was generated with.
    • Use EU region: Optionally enable this toggle to use the EU region of New Relic.
  4. Click Save.
Once you save your configuration, you’ll see it listed on the integration’s settings page in Cortex. If you’ve set everything up correctly, you’ll see the option to Remove Integration in Settings. You can also use the Test all configurations button to confirm that the configuration was successful. If your configuration is valid, you’ll see a banner that says “Configuration is valid. If you see issues, please see documentation or reach out to Cortex support.”

​
Cross-account access

After setting up the integration, you will be redirected to the New Relic settings page where you can enable the cross-account access feature. If you have an account that supports subordinate accounts, you can enable this setting to fetch applications and SLOs for all the accounts that are under the configured one.

​
Configure the integration for multiple New Relic accounts↗

The New Relic integration has multi-account support. You can add a configuration for each additional by repeating the process above. Each configuration requires an alias, which Cortex uses to correlate the designated with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the New Relic page in your Cortex settings. Select the edit icon next to a given configuration and toggle Set as default on. If you only have one configuration, it will automatically be set as the default.

​
How to connect Cortex entities to New Relic

​
Auto discovery

There are two ways to auto-map New Relic applications and services to Cortex entities:
  • By default, Cortex will use the Cortex tag (e.g. my-entity) or its name as the “best guess” for New Relic applications. For example, if your Cortex tag is my-entity, then the corresponding application in New Relic should also be my-entity. The name is not case-sensitive.
    • If your New Relic applications don’t cleanly match the Cortex tag or name, you can override this in the Cortex entity descriptor.
  • Cortex also supports mapping New Relic applications to Cortex entities via New Relic tagKeys. By default, a Cortex entity will be mapped to a New Relic application or service with New Relic tag key = “service” and tag value = the service’s Cortex tag.
Note: Cortex does not support auto-mapping of SLOs. SLOs have to be defined via the entity YAML or attached to a mapped application or service. Dependencies Cortex automatically maps dependencies between your entities by utilizing New Relic’s Service Map data. Say you have two applications in NewRelic (Application A and Application B), and in the service map Application A calls Application B. In Cortex you have two Entities (Cortex Entity A and Cortex Entity B), where Cortex Entity A is mapped to New Relic Application A and Cortex Entity B is mapped to New Relic Application B. Cortex will take the mapped relationship from Application A to Application B and create a dependency from Cortex Entity A to Cortex Entity B.

​
Import entities from New Relic

See the Create services documentation for instructions on importing entities.

​
Editing the entity descriptor

APM services New Relic application metrics can be fetched for each entity using application IDs or tags.
While the applications wrapper format is the recommended format, Cortex also supports a flat array:
Instructions to find your Application ID can be found in the New Relic docs. You can also find the Application ID in the URL in New Relic. You can also find information on finding and managing tags in the New Relic docs. OpenTelemetry OpenTelemetry services can be associated with the entity only using tags. For this type of service New Relic doesn’t generate application ID.
Cortex fetches OpenTelemetry data every 5 minutes, but the data refresh may take longer depending on how much data you have. Embeds Cortex can also embed dashboards from New Relic.
Learn more about embedding charts in the Adding external docs page. SLOs SLO can be fetched for each entity using New Relic entity GUID for respective SLO or associated service. Detailed instructions how to obtain entity GUID can be found in New Relic docs. Fetched SLO information can be found in the Operations and Integrations sections of an entity page.
If the alias is not specified, like with the third ID above, Cortex will use the default configuration. If you use the GUID for a parent service to define the SLOs for a given entity, Cortex will import all SLOs associated with that service.

​
Using the New Relic integration

​
View New Relic data on entity pages

When entities are tied to New Relic, SLO and monitoring information appear under the Monitoring section on the overview of the entity details page. More data is available under the Monitoring page in the entity’s sidebar:
  • Throughput
  • Response time
  • Error rate
  • Apdex target
  • Apdex score
  • Host count
  • Instance count
  • Concurrent instance count
In the SLOs section, you’ll be able to see a list of all SLOs tied to that entity, the target and current SLO score, and the period of time the SLO is being calculated for. For example, if the time listed is “7 days ago,” then the SLO is looking at the time range starting 7 days ago to now.. The SLO name will display in green when passing and orange when failing. If you’ve defined dashboards in an entity’s YAML, you’ll be able to view the graphs from an entity’s details page. Open the Dashboard page in the entity’s sidebar. All dashboards defined in the descriptor will be embedded on this page. New Relic dashboards must be defined individually for each entity.

​
Relationship graphs

Dependencies detected from New Relic will appear in Relationship graphs. You can manually sync dependencies in the Relationship Graph.

​
Scorecards and CQL

With the New Relic integration, you can create Scorecard rules and write CQL queries based on New Relic performance metrics. See more examples in the CQL Explorer in Cortex.
Fetch high-level summary data for a given New Relic application.This expression enables you to score entities on reliability metrics:
  • Apdex score
  • Apdex target
  • Concurrent stance count
  • Error rate
  • GUID
  • Host count
  • ID
  • Instance count
  • Name
  • Response time
  • Throughput
  • Type
If there is not an application ID set in the entity descriptor, a Scorecard rule based on this expression will fail.Definition: newrelic.applications()ExampleYou can use this expression in a Scorecard rule to make sure entities’ Apdex score is at least 0.9:
Check if entity has a New Relic application ID set in its entity descriptor.This can be a good companion to other rules that will fail without a defined application ID, like newrelic.applications().Definition: newrelic (==/!=) nullExampleYou can use this expression in an onboarding Scorecard to make sure that entities have a New Relic application ID set:
Execute an arbitrary NRQL query and capture the raw JSON back out.This expression is not inherently tied to a single entity and requires a custom query to pull the specific data what you need. The raw JSON can be parsed using JQ or Open Policy Agent language.Definition: newrelic.rawNrql(query: Text)ExamplesYou can use this expression in a Scorecard measuring performance to make sure that the 95th percentile of latency has been less than 500ms in the last 3 weeks for a given entity:
Or you can use this expression in a CQL report to read the timeseries of the process.cpu.usage metric for the last 30 minutes using NRQL and a New Relic service GUID:
SLOs associated with the entity via ID or tags. You can use this data to check whether an entity has SLOs associated with it and if those SLOs are passing.SLOs
  • History
  • ID
  • Name
  • Operation
  • Remaining budget
  • SLI value
  • SLO target
  • Source
  • Thresholds
SLO datum (timeseries data for the SLI)
  • Datum
  • Ts
Named threshold (SLOs thresholds like “warning” or “error” states)
  • Name
  • Threshold
Definition: slosExamplesYou can use SLO data from New Relic to evaluate entities in Scorecards. For an onboarding Scorecard, you can make sure that entities have at least 1 SLO defined:
For a project standards Scorecard, you can also use this expression to make sure entities are passing all of their SLOs:
OpenTelemetry metrics OpenTelemetry metrics available in the New Relic Metrics Exlorer can be accessed or manipulated for a given entity by combining CQL and NRQL native query.
In Cortex, you can access OpenTelemetry data by incorporating a raw NRQL query into this CQL expression with the associated New Relic GUID.Definition: newrelic.applications().getOrNull(0)?.guidExampleYou can execute raw NRQL query to collect average http.server.requests in a CQL report:

​
View integration logs

This feature is available in Cortex cloud.
While viewing an integration’s settings page, select the Error logs tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).
The 'Logs' tab on an integration's settings page shows error information over the past 7 days.
Click into a row to get more information, including time stamp, status code, full error, and request path.

​
Still need help?↗

The following options are available to get assistance from the Cortex Customer Engineering team:
  • Email: help@cortex.io, or open a support ticket in the in app Resource Center
  • Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Last modified on September 9, 2026