New Relic Cheatsheet

New Relic Cheatsheet

Installation

Infrastructure Agent

Platform	Command
Ubuntu/Debian	`curl https://download.newrelic.com/infrastructure_agent/gpg/newrelic-infra.gpg \
RHEL/CentOS	sudo curl -o /etc/yum.repos.d/newrelic-infra.repo https://download.newrelic.com/infrastructure_agent/linux/yum/el/7/x86_64/newrelic-infra.repo && sudo yum install newrelic-infra -y
macOS	brew install newrelic-infra-agent
Windows (PowerShell)	choco install newrelic-infra -y --params="'/LICENSE_KEY:YOUR_LICENSE_KEY'"
Docker	docker run -d --name newrelic-infra --network=host --cap-add=SYS_PTRACE --privileged --pid=host -v "/:/host:ro" -v "/var/run/docker.sock:/var/run/docker.sock" -e NRIA_LICENSE_KEY=YOUR_KEY newrelic/infrastructure:latest

New Relic CLI

Platform	Command
Linux/macOS	`curl -Ls https://download.newrelic.com/install/newrelic-cli/scripts/install.sh \
macOS (Homebrew)	brew install newrelic-cli
Linux (Snap)	sudo snap install newrelic-cli
Windows (Scoop)	scoop bucket add newrelic-cli https://github.com/newrelic/newrelic-cli.git && scoop install newrelic-cli

APM Agents

Language	Command
Node.js	npm install newrelic --save
Python	pip install newrelic
Java	curl -O https://download.newrelic.com/newrelic/java-agent/newrelic-agent/current/newrelic-java.zip && unzip newrelic-java.zip
Ruby	gem 'newrelic_rpm' (add to Gemfile)
PHP	sudo apt-get install newrelic-php5 (Ubuntu) or sudo yum install newrelic-php5 (RHEL)
.NET	Download from https://download.newrelic.com/dot_net_agent/latest_release/

Basic Commands

CLI Profile Management

Command	Description
newrelic profile add --profile production --apiKey YOUR_KEY --region us	Add new profile with API key
newrelic profile list	List all configured profiles
newrelic profile default --profile production	Set default profile
newrelic profile delete --profile staging	Delete a profile
newrelic profile get --profile production	View profile details

Entity Management

Command	Description
newrelic entity search --name "my-app"	Search for entities by name
newrelic entity search --type APPLICATION	Search entities by type
newrelic entity get --guid ENTITY_GUID	Get detailed entity information
newrelic entity tags get --guid ENTITY_GUID	List all tags for an entity
newrelic entity tags create --guid ENTITY_GUID --tag "env:prod"	Add tag to entity
newrelic entity tags delete --guid ENTITY_GUID --tag "env:staging"	Remove tag from entity

Infrastructure Agent Control

Command	Description
sudo systemctl status newrelic-infra	Check agent status
sudo systemctl start newrelic-infra	Start infrastructure agent
sudo systemctl stop newrelic-infra	Stop infrastructure agent
sudo systemctl restart newrelic-infra	Restart infrastructure agent
sudo systemctl enable newrelic-infra	Enable agent at boot
sudo tail -f /var/log/newrelic-infra/newrelic-infra.log	View agent logs in real-time
sudo newrelic-infra -dry_run -config_file /etc/newrelic-infra.yml	Test configuration without starting
newrelic-infra --version	Display agent version

Advanced Usage

NRQL Queries

Command	Description
newrelic nrql query --accountId ACCT_ID --query "SELECT count(*) FROM Transaction SINCE 1 hour ago"	Execute basic NRQL query
newrelic nrql query --accountId ACCT_ID --query "SELECT average(duration) FROM Transaction FACET appName SINCE 1 day ago"	Query with faceting
newrelic nrql query --accountId ACCT_ID --query "SELECT * FROM Log WHERE message LIKE '%error%' SINCE 30 minutes ago LIMIT 100"	Search logs with filtering
newrelic nrql query --accountId ACCT_ID --query "SELECT percentile(duration, 95, 99) FROM Transaction SINCE 1 hour ago" --format json	Get percentiles with JSON output
newrelic nrql query --accountId ACCT_ID --query "SELECT rate(count(*), 1 minute) FROM Transaction TIMESERIES SINCE 1 hour ago"	Calculate rate with time series

Deployment Management

Command	Description
newrelic apm deployment create --applicationId APP_ID --revision "v1.2.3" --changelog "Bug fixes"	Create deployment marker
newrelic apm deployment create --applicationId APP_ID --revision "v2.0.0" --user "jenkins" --description "Major release"	Create detailed deployment marker
newrelic apm deployment list --applicationId APP_ID	List all deployments for application

Workload Management

Command	Description
newrelic workload create --accountId ACCT_ID --name "Production Stack" --entityGuids "GUID1,GUID2"	Create new workload
newrelic workload get --guid WORKLOAD_GUID	Get workload details
newrelic workload update --guid WORKLOAD_GUID --name "Updated Stack"	Update workload name
newrelic workload delete --guid WORKLOAD_GUID	Delete workload
newrelic workload list --accountId ACCT_ID	List all workloads in account

Alert Management

Command	Description
newrelic alerts policy create --accountId ACCT_ID --name "Production Alerts" --incidentPreference PER_CONDITION	Create alert policy
newrelic alerts policy list --accountId ACCT_ID	List all alert policies
newrelic alerts condition list --policyId POLICY_ID	List conditions for policy
newrelic alerts channel list --accountId ACCT_ID	List notification channels

Dashboard Management

Command	Description
newrelic dashboard create --accountId ACCT_ID --name "My Dashboard"	Create new dashboard
newrelic dashboard list --accountId ACCT_ID	List all dashboards
newrelic dashboard get --guid DASHBOARD_GUID	Get dashboard configuration
newrelic dashboard delete --guid DASHBOARD_GUID	Delete dashboard

Configuration

Infrastructure Agent Configuration (/etc/newrelic-infra.yml)

# Required: License key
license_key: YOUR_LICENSE_KEY

# Optional: Custom display name
display_name: web-server-01

# Logging configuration
log_file: /var/log/newrelic-infra/newrelic-infra.log
log_level: info  # Options: error, warn, info, debug, trace

# Proxy configuration
proxy: http://proxy.example.com:8080
proxy_validate_certificates: true

# Custom attributes (tags)
custom_attributes:
  environment: production
  team: platform
  region: us-east-1

# Metrics configuration
disable_all_plugins: false
metrics_network_sample_rate: 10  # seconds
metrics_process_sample_rate: 20  # seconds
metrics_storage_sample_rate: 20  # seconds

# Process monitoring
enable_process_metrics: true

APM Agent Configuration (Node.js - newrelic.js)

'use strict'

exports.config = {
  app_name: ['My Application'],
  license_key: 'YOUR_LICENSE_KEY',
  
  logging: {
    level: 'info',
    filepath: 'stdout'
  },
  
  // Distributed tracing
  distributed_tracing: {
    enabled: true
  },
  
  // Transaction tracer
  transaction_tracer: {
    enabled: true,
    transaction_threshold: 'apdex_f',
    record_sql: 'obfuscated',
    explain_threshold: 500
  },
  
  // Error collector
  error_collector: {
    enabled: true,
    ignore_status_codes: [404]
  },
  
  // Custom attributes
  attributes: {
    include: ['request.parameters.*'],
    exclude: ['request.headers.cookie']
  }
}

Python Agent Configuration (newrelic.ini)

[newrelic]
license_key = YOUR_LICENSE_KEY
app_name = Python Application

# Logging
log_file = stdout
log_level = info

# Distributed tracing
distributed_tracing.enabled = true

# Transaction tracer
transaction_tracer.enabled = true
transaction_tracer.transaction_threshold = apdex_f
transaction_tracer.record_sql = obfuscated
transaction_tracer.explain_threshold = 0.5

# Error collector
error_collector.enabled = true
error_collector.ignore_status_codes = 404

# Browser monitoring
browser_monitoring.auto_instrument = true

# Custom attributes
attributes.include = request.parameters.*
attributes.exclude = request.headers.cookie

CLI Configuration (~/.newrelic/newrelic-cli.json)

{
  "defaultProfile": "production",
  "profiles": {
    "production": {
      "apiKey": "YOUR_USER_API_KEY",
      "region": "us",
      "accountId": "YOUR_ACCOUNT_ID"
    },
    "staging": {
      "apiKey": "YOUR_STAGING_API_KEY",
      "region": "us",
      "accountId": "YOUR_STAGING_ACCOUNT_ID"
    }
  }
}

Common Use Cases

Use Case 1: Monitor Application Performance

# Install Node.js APM agent
npm install newrelic --save

# Generate configuration
cp node_modules/newrelic/newrelic.js .

# Edit configuration file with your license key
# license_key: 'YOUR_LICENSE_KEY'
# app_name: ['My Application']

# Add to the first line of your main application file
# require('newrelic');

# Start application
node app.js

# Query transaction performance
newrelic nrql query --accountId YOUR_ACCOUNT_ID \
  --query "SELECT average(duration), percentile(duration, 95) FROM Transaction WHERE appName = 'My Application' SINCE 1 hour ago"

Use Case 2: Set Up Infrastructure Monitoring with Custom Tags

# Install infrastructure agent
curl -Ls https://download.newrelic.com/install/newrelic-cli/scripts/install.sh | bash

# Configure with custom attributes
sudo tee /etc/newrelic-infra.yml << EOF
license_key: YOUR_LICENSE_KEY
display_name: web-server-01
custom_attributes:
  environment: production
  team: platform
  datacenter: us-east-1
  role: webserver
EOF

# Start the agent
sudo systemctl start newrelic-infra
sudo systemctl enable newrelic-infra

# Verify it's reporting
newrelic entity search --name "web-server-01"

# Query infrastructure metrics
newrelic nrql query --accountId YOUR_ACCOUNT_ID \
  --query "SELECT average(cpuPercent), average(memoryUsedPercent) FROM SystemSample WHERE environment = 'production' FACET hostname SINCE 1 hour ago"

Use Case 3: Create Deployment Markers for Release Tracking

# Configure CLI profile
newrelic profile add --profile production \
  --apiKey YOUR_USER_API_KEY \
  --region us \
  --accountId YOUR_ACCOUNT_ID

# Get application ID
APP_ID=$(newrelic entity search --name "My Application" --type APPLICATION | grep -oP 'id: \K\d+')

# Create deployment marker during CI/CD
newrelic apm deployment create \
  --applicationId $APP_ID \
  --revision "v2.5.0" \
  --changelog "Added new feature X, fixed bug Y" \
  --description "Production deployment from Jenkins" \
  --user "$USER"

# Query performance before and after deployment
newrelic nrql query --accountId YOUR_ACCOUNT_ID \
  --query "SELECT average(duration) FROM Transaction WHERE appName = 'My Application' SINCE 2 hours ago TIMESERIES 10 minutes"

Use Case 4: Centralized Log Management

# Configure infrastructure agent to forward logs
sudo tee -a /etc/newrelic-infra.yml << EOF
log_forward:
  - name: application-logs
    file: /var/log/myapp/*.log
    attributes:
      logtype: application
      environment: production
EOF

# Restart agent
sudo systemctl restart newrelic-infra

# Search logs for errors
newrelic nrql query --accountId YOUR_ACCOUNT_ID \
  --query "SELECT * FROM Log WHERE logtype = 'application' AND message LIKE '%ERROR%' SINCE 30 minutes ago LIMIT 100"

# Analyze error patterns
newrelic nrql query --accountId YOUR_ACCOUNT_ID \
  --query "SELECT count(*) FROM Log WHERE logtype = 'application' AND message LIKE '%ERROR%' FACET message SINCE 1 day ago"

Use Case 5: Create Custom Dashboard with CLI

# Create dashboard with multiple widgets
newrelic dashboard create --accountId YOUR_ACCOUNT_ID << 'EOF'
{
  "name": "Production Overview",
  "permissions": "PUBLIC_READ_WRITE",
  "pages": [
    {
      "name": "Application Performance",
      "widgets": [
        {
          "title": "Average Response Time",
          "visualization": { "id": "viz.line" },
          "rawConfiguration": {
            "nrqlQueries": [
              {
                "accountId": YOUR_ACCOUNT_ID,
                "query": "SELECT average(duration) FROM Transaction TIMESERIES AUTO"
              }
            ]
          }
        }
      ]
    }
  ]
}
EOF

# List dashboards
newrelic dashboard list --accountId YOUR_ACCOUNT_ID

Best Practices

• Use Custom Attributes: Tag all entities with environment, team, and purpose metadata for better filtering and organization. Add custom attributes in agent configuration files to automatically categorize all metrics.

• Implement Distributed Tracing: Enable distributed tracing in all APM agents to track requests across microservices. This provides end-to-end visibility and helps identify bottlenecks in complex architectures.

• Set Up Deployment Markers: Create deployment markers for every production release to correlate performance changes with code deployments. This dramatically reduces troubleshooting time when issues arise.

• Configure Alert Policies Properly: Use baseline alerts for dynamic thresholds and static alerts for known limits. Set up multiple notification channels and use incident intelligence to reduce alert fatigue.

• Optimize Data Retention: Use data management tools to control data ingest and retention. Drop unnecessary metrics, aggregate data appropriately, and use sampling for high-volume applications to manage costs.

• Leverage Workloads: Group related entities into workloads to monitor entire application stacks together. This provides a unified view of health status and simplifies team collaboration.

• Use NRQL Effectively: Master NRQL for custom queries and dashboards. Use FACET for grouping, TIMESERIES for trends, and percentile() for meaningful performance metrics instead of just averages.

• Implement Synthetic Monitoring: Set up synthetic monitors for critical user journeys and API endpoints from multiple geographic locations. This provides proactive alerting before users experience issues.

• Secure Your API Keys: Use user API keys for CLI operations and license keys for agents. Rotate keys regularly, use different keys per environment, and never commit keys to version control.

Troubleshooting

Issue	Solution
Agent not reporting data	Check license key in configuration file, verify network connectivity to New Relic endpoints (collector.newrelic.com), check agent logs for errors: sudo tail -f /var/log/newrelic-infra/newrelic-infra.log
High memory usage by infrastructure agent	Reduce sampling rates in /etc/newrelic-infra.yml: set metrics_network_sample_rate: 60, metrics_process_sample_rate: 60, disable unnecessary integrations
APM agent causing application slowdown	Reduce transaction trace threshold, disable slow SQL trace collection, or adjust sampling rate in agent configuration. For Node.js: set transaction_tracer.enabled: false temporarily
Missing distributed traces	Ensure all services have distributed tracing enabled in agent config, verify compatible agent versions (check compatibility matrix), ensure trace context headers are propagated through middleware
CLI authentication failures	Regenerate user API key from New Relic UI (Account Settings > API Keys), verify region setting (US vs EU): newrelic profile add --region us, check API key permissions
Data not appearing in queries	Verify correct account ID, check data type (Transaction vs TransactionError), ensure time range is appropriate (SINCE 1 hour ago), verify entity is reporting: newrelic entity search --name "app-name"
Docker agent not collecting container metrics	Ensure proper volume mounts: -v "/var/run/docker.sock:/var/run/docker.sock", run with --privileged flag, verify --pid=host is set for process monitoring
Logs not forwarding	Check log file paths in /etc/newrelic-infra.yml, verify file permissions (agent must read logs), ensure log forwarding is enabled, check for parsing errors in agent logs
High data ingest costs	Review data ingest in Data Management UI, implement drop rules for unnecessary data, reduce APM transaction trace sampling, disable detailed process metrics if not needed
Alert notifications not received	Verify notification channel configuration, check incident preference settings on alert policy, ensure conditions have proper thresholds, test notification channel from UI

Quick Reference: Common NRQL Queries

-- Average response time by application
SELECT average(duration) FROM Transaction FACET appName SINCE 1 hour ago

-- Error rate percentage
SELECT percentage(count(*), WHERE error IS true) FROM Transaction SINCE 1 hour ago

-- 95th and 99th percentile response times
SELECT percentile(duration, 95, 99) FROM Transaction SINCE 1 day ago TIMESERIES

-- Top 10 slowest transactions
SELECT average(duration), count(*) FROM Transaction FACET name SINCE 1 hour ago LIMIT 10

-- Infrastructure CPU usage
SELECT average(cpuPercent) FROM SystemSample FACET hostname SINCE 1 hour ago

-- Log error count by message
SELECT count(*) FROM Log WHERE level = 'error' FACET message SINCE 1 hour ago

-- Request throughput per minute
SELECT rate(count(*), 1 minute) FROM Transaction TIMESERIES SINCE 1 hour ago

-- Database query performance
SELECT average(databaseDuration) FROM Transaction FACET databaseType SINCE 1 hour ago