Skip to main content

New Relic

New Relic is a comprehensive observability platform that provides real-time insights into application performance, infrastructure health, and user experiences. It offers application performance monitoring (APM), infrastructure monitoring, log management, synthetic monitoring, and powerful query capabilities through NRQL (New Relic Query Language).

Authentication Types​

New Relic supports API Key authentication:

  • API Key - User API Key authentication
    • Pros: Simple to set up, secure, supports all API operations
    • Cons: Keys must be rotated manually for security best practices
    • Best for: All use cases

General Settings​

Before using the connector, you need to configure:

  • Region - Your New Relic data center region
    • US - United States (default) - api.newrelic.com
    • EU - European Union - api.eu.newrelic.com
  • Account ID - Your New Relic account ID (required for most operations)
    • Find this in your New Relic account URL or account settings
    • Format: Numeric ID (e.g., 123456)

Setting up API Key​

Follow these steps to create a User API Key for New Relic:

  1. Log in to New Relic One

  2. Click on your user name in the bottom left corner

  3. Select API keys from the menu

  4. Click Create a key button

  5. Choose the following settings:

    • Key type: User key
    • Name: Enter a descriptive name (e.g., "MCP Connector")
    • Account: Select your account
    • Notes: (Optional) Add a description

  6. Click Create a key

  7. Copy the key immediately - it will only be shown once

  8. Save the key securely - you'll need it to configure the connector

  9. Also note your Account ID:

    • It's displayed in the account dropdown
    • Or find it in your New Relic URL: https://one.newrelic.com/accounts/[YOUR_ACCOUNT_ID]
tip

User API Keys are tied to your user account and inherit your permissions. Make sure you have the necessary permissions to access the data and features you need.

Key Capabilities​

Entity Management​

  • Search and discover all monitored entities (applications, hosts, services)
  • Get detailed entity information including tags and relationships
  • Query golden metrics for any entity type
  • Understand your entire monitoring landscape

NRQL Queries​

  • Execute powerful NRQL queries against your telemetry data
  • Query across multiple accounts simultaneously
  • Run long-running queries asynchronously
  • Access all event types: metrics, events, logs, and traces

Alerts​

  • List and inspect alert policies and conditions
  • Search recent alert violations and incidents
  • View muting rules and understand alert suppression
  • Monitor your alerting configuration

Dashboards​

  • Discover and list all dashboards
  • Retrieve complete dashboard configurations
  • Extract widget queries for analysis
  • Search dashboards by name or tags

Synthetic Monitoring​

  • List all synthetic monitors
  • Get monitor configurations and scripts
  • Retrieve recent execution results
  • Track uptime and performance from global locations

Application Performance Monitoring (APM)​

  • List all APM-monitored applications
  • Get application performance metrics
  • Track deployments and correlate with performance
  • Monitor application health and errors

Infrastructure​

  • List monitored hosts and servers
  • Get infrastructure metrics (CPU, memory, disk, network)
  • Monitor system health and resource usage
  • Track infrastructure performance

Common Use Cases​

Performance Investigation​

1. Use "Search Entities" to find your application
2. Use "Query Entity Golden Metrics" to see key performance indicators
3. Use "Execute NRQL Query" to dive deeper into specific metrics
4. Use "Get Application Metrics" for detailed APM data

Alert Analysis​

1. Use "Search Alert Violations" to find recent incidents
2. Use "List Alert Policies" to understand alerting setup
3. Use "Get Alert Policy" to inspect specific policy configurations
4. Use "List Muting Rules" to check if alerts are suppressed

Dashboard Analysis​

1. Use "List Dashboards" to discover available dashboards
2. Use "Get Dashboard" to retrieve dashboard configuration
3. Use "Get Dashboard Widgets" to extract widget queries
4. Use "Execute NRQL Query" to run extracted queries with modifications

Infrastructure Monitoring​

1. Use "List Infrastructure Hosts" to find your servers
2. Use "Get Host Metrics" to check resource usage
3. Use "Execute NRQL Query" to analyze infrastructure data
4. Correlate infrastructure metrics with application performance

API Regions​

New Relic operates in two data center regions:

  • US Region (default): api.newrelic.com

    • Used by most customers
    • Stores data in United States data centers

  • EU Region: api.eu.newrelic.com

    • For customers requiring data residency in Europe
    • Stores data in European Union data centers

Make sure to select the correct region in your connector settings based on where your New Relic account is hosted. You can verify your region by checking your New Relic URL:

  • US accounts: one.newrelic.com
  • EU accounts: one.eu.newrelic.com

Rate Limits​

New Relic APIs have the following rate limits:

  • NerdGraph (GraphQL):
    • 25 requests per second per API key
    • 3,000 requests per minute per account
  • NRQL Queries:
    • 3,000 queries per account per minute
    • Query timeout: 30-120 seconds (configurable)

If you exceed rate limits, you'll receive a 429 error. Implement exponential backoff and retry logic in your applications.

Troubleshooting​

Authentication Errors​

Error: 401 Unauthorized or Invalid API Key

Cause: The API key is incorrect, expired, or lacks necessary permissions

Solution:

  1. Verify the API key is correct and hasn't been deleted
  2. Ensure the key is a User Key, not a License Key or Browser Key
  3. Check that the user associated with the key has appropriate permissions
  4. Create a new API key if needed

Account ID Errors​

Error: Account not found or Access denied

Cause: The Account ID is incorrect or the API key doesn't have access to that account

Solution:

  1. Verify the Account ID matches your New Relic account
  2. Check your account ID in New Relic One: Click your name → API keys
  3. Ensure your API key has access to the specified account
  4. For multi-account organizations, verify you're using the correct account ID

Region Configuration​

Error: Connection timeout or Unable to reach API

Cause: The region setting doesn't match your account's actual region

Solution:

  1. Verify your New Relic region:
    • US: one.newrelic.com
    • EU: one.eu.newrelic.com
  2. Update the Region setting in connector configuration to match
  3. Restart the connector after changing the region

Query Timeout​

Error: Query timeout exceeded

Cause: NRQL query is too complex or querying too much data

Solution:

  1. Reduce the time range in your query (e.g., use SINCE 1 hour ago instead of SINCE 30 days ago)
  2. Limit the number of results with LIMIT clause
  3. Use "Execute Async NRQL Query" for long-running queries
  4. Optimize your query by filtering early and reducing aggregations

Entity Not Found​

Error: Entity with GUID not found

Cause: The entity GUID is incorrect, or the entity has been deleted

Solution:

  1. Verify the GUID is correct (should be a long alphanumeric string)
  2. Use "Search Entities" to find the correct GUID
  3. Check if the entity is still reporting data (may have been decommissioned)
  4. Ensure you're querying the correct account

Rate Limiting​

Error: 429 Too Many Requests

Cause: You've exceeded the API rate limits

Solution:

  1. Implement request throttling in your application
  2. Use exponential backoff for retries
  3. Batch multiple queries when possible
  4. Spread requests over time rather than bursting
  5. Consider using async queries for heavy workloads

Best Practices​

Query Optimization​

  • Always include time ranges in NRQL queries (SINCE, UNTIL)
  • Use LIMIT to restrict result sizes
  • Filter early in your queries to reduce data processed
  • Use async queries for complex or long-running operations

Entity Discovery​

  • Use tags to organize and filter entities effectively
  • Leverage entity search query syntax for powerful filtering
  • Cache entity GUIDs when possible to reduce search queries

Dashboard Usage​

  • Extract and modify widget queries for custom analysis
  • Use dashboard variables to make queries more flexible
  • Export dashboard configurations for backup or migration

Alert Management​

  • Regularly review muting rules to ensure alerts aren't permanently silenced
  • Use alert policies to group related conditions
  • Monitor alert violations to identify recurring issues

Security​

  • Rotate API keys periodically (recommended: every 90 days)
  • Use separate API keys for different applications or teams
  • Limit API key permissions to what's actually needed
  • Never commit API keys to version control

Additional Resources​