New Relic Diagnostics

Download latest version

New Relic Diagnostics is a utility that automatically detects common problems with New Relic agents. If Diagnostics detects a problem, it suggests troubleshooting steps. New Relic Diagnostics can also automatically attach troubleshooting data to a New Relic Support ticket.

For additional troubleshooting steps for your agent, see Not seeing data.

Licensing and security

The use of New Relic Diagnostics is subject to this license agreement, as well as licensing agreements for open-source software used by New Relic Diagnostics.

Like any other New Relic product or service, the Diagnostic service is designed to protect you and your customers' data privacy. For more information about New Relic's security measures, see our security and privacy documentation, or visit the New Relic security website.

New Relic Diagnostics examines the following environment variables to perform diagnostic checks. The values of these variables are recorded locally in the nrdiag-output.json file.

Environment variables
  • Any environment variable containing NEWRELIC or NEW_RELIC
  • Any environment variable beginning with NRIA
  • PATH
  • HOME
  • RUBY_ENV
  • RAILS_ENV
  • APP_ENV
  • RACK_ENV
  • LOCALAPPDATA
  • DOTNET_SDK_VERSION
  • DOTNET_INSTALL_PATH
  • COR_PROFILER
  • COR_PROFILER_PATH
  • COR_ENABLE_PROFILER
  • CORECLR_ENABLE_PROFILING
  • CORECLR_PROFILER
  • CORECLR_PROFILER_PATH
  • ProgramFiles
  • ProgramData
  • APPDATA
  • JBOSS_HOME
  • JAVA_VERSION_MAJOR
  • JAVA_VERSION_MINOR
  • JAVA_VERSION_BUILD
  • JAVA_PACKAGE
  • JAVA_JCE
  • JAVA_HOME
  • GLIBC_REPO
  • GLIBC_VERSION
  • LANG
  • WORKDIR
  • MINION_JAR
  • DEFAULT_LOCALE_CFG_FILE
  • MINION_PROVIDER
  • MINION_USER
  • MINION_GROUP
  • MINION_LOG_LEVEL
  • DOCKER_API_VERSION
  • DOCKER_HOST
  • MINION_API_ENDPOINT
  • MINION_DOCKER_RUNNER_REGISTRY_ENDPOINT
  • MINION_API_PROXY
  • MINION_API_PROXY_SELF_SIGNED_CERT
  • MINION_CHECK_TIMEOUT
  • MINION_DOCKER_API_VERSION
  • MINION_DOCKER_HOST
  • MINION_DOCKER_RUNNER_APPARMOR
  • MINION_JVM_MB
  • MINION_JVM_OPTS

Compatibility

New Relic Diagnostics is available for Linux, macOS, and Windows. It can detect common configuration issues for:

  • New Relic APM: Available for all APM agents except C SDK. For the Go agent, only basic connectivity checks are available.

  • New Relic Browser: Browser agent detection
  • New Relic Infrastructure: Linux and Windows agents
  • New Relic Synthetics: Synthetics private minions

Diagnostics does not require superuser permissions to run, although New Relic does recommend those permissions for some checks. It will return an error if it does not have permissions to read the files it scans.

Run New Relic Diagnostics

To use New Relic Diagnostics:

  1. Review the release notes, to make sure you have the latest version.
  2. Download the latest version, which contains executable files for Linux, macOS, and Windows.
  3. Move the executable for your platform into the location of the agent's root directory, which depends on the New Relic agent.
  4. Recommendation: Temporarily raise the logging level for the New Relic agent you are troubleshooting.
  5. Run the executable.

New Relic Diagnostics automatically searches its root directory and subdirectories for agent configuration files and other relevant data. To run Diagnostics, follow the procedures for your platform:

Linux
  1. Ensure you have New Relic Diagnostics:

  2. Unzip nrdiag.zip if necessary.
  3. From the nrdiag_1.2.3/linux directory, move nrdiag into the agent's root directory.
  4. Run nrdiag (along with any CLI options or a ticket attachment key):

    ./nrdiag CLI_OPTIONS

New Relic Diagnostics outputs any issues it discovers, and uploads relevant files to your New Relic Support ticket if you include a ticket attachment key.

macOS
  1. Ensure you have New Relic Diagnostics:

  2. Unzip nrdiag.zip if necessary.
  3. From the nrdiag_1.2.3/mac directory, move nrdiag into the agent root directory.
  4. Run nrdiag (along with any CLI options, or a ticket attachment key):

    ./nrdiag CLI_OPTIONS

New Relic Diagnostics outputs any issues it discovers, and uploads relevant files to your New Relic Support ticket if you include a ticket attachment key.

Windows
  1. Ensure you have New Relic Diagnostics:

  2. Unzip nrdiag.zip if necessary.
  3. From the nrdiag_1.2.3/win directory, move nrdiag.exe or nrdiag_x64.exe into the agent root directory (for .NET Framework apps, move it into the application root directory).
  4. For troubleshooting web applications, ensure you are running the executable from your project's parent directory, or specify your config file location with the -c option.
  5. Run the executable (along with any CLI options or a ticket attachment key) from the directory you placed the binary. Since some checks require elevated permissions, for best results run from an Admin shell.

    Run via PowerShell if you add any CLI_OPTIONS:

    ./nrdiag.exe CLI_OPTIONS

    OR, for x64 systems:

    ./nrdiag_x64.exe CLI_OPTIONS

New Relic Diagnostics outputs any issues it discovers, and it uploads relevant files to your New Relic Support ticket if you include a ticket attachment key.

New Relic Browser
  1. Ensure you have New Relic Diagnostics:

  2. Unzip nrdiag.zip if necessary.
  3. From the nrdiag_1.2.3/OS directory, run nrdiag (along with any CLI options or a ticket attachment key):
    ./nrdiag -browser-url WEBSITE_URL CLI_OPTIONS

New Relic Diagnostics outputs any issues it discovers, and uploads relevant files to your New Relic Support ticket if you include a ticket attachment key.

New Relic Synthetics private minions

Once you have logged into the private minion via SSH, New Relic Diagnostics appears in the /opt/newrelic/synthetics directory:

  1. Log in to your private minion via SSH.

  2. Change directory:

    cd /opt/newrelic/synthetics
  3. Unzip nrdiag.zip if necessary.
  4. From the nrdiag_1.2.3/linux directory, move nrdiag into /opt/newrelic/synthetics.
  5. Run nrdiag (along with any CLI options or a ticket attachment key):

    ./nrdiag CLI_OPTIONS

New Relic Diagnostics outputs any issues it discovers, and it uploads relevant files to your New Relic Support ticket if you included an attachment key.

View or copy attachment key

New Relic Support generates an attachment key for your support ticket, which is used with Diagnostics. To view or copy your attachment key:

  1. Log in to your New Relic account at rpm.newrelic.com, then select Help > Get support.
  2. Select View open tickets, then select the ticket.
  3. Copy the NR Diagnostics attachment key that appears at the top of the ticket. If you do not see the attachment key code, notify Support.

Use this attachment key to upload your Diagnostics results to your support ticket.

Upload results to a support ticket

If your system is configured to not connect to external IP addresses, this method will not work. Instead, attach the output files in an email to New Relic Support.

Automatic upload

To upload your results automatically to a New Relic Support ticket when New Relic Diagnostics is executed, use the -attachment-key command line flag with your ticket's attachment key:

System Command line flag
Linux, macOS, Synthetics private minion
./nrdiag -attachment-key ATTACHMENT_KEY
Windows (to run from PowerShell add ./ to start of cmd)

For 32-bit systems:

nrdiag.exe -attachment-key ATTACHMENT_KEY

For 64-bit systems:

nrdiag_x64.exe -attachment-key ATTACHMENT_KEY

Uploading your results to a support ticket will automatically upload the contents of nrdiag-output.zip. If you would like to inspect or modify the contents of this file before upload, please follow the manual upload process.

Manual upload

If you've modified and/or inspected the content of nrdiag-output.zip and would like to attach it to a support ticket, you can use the -file-upload and -attachment-key command line flags together to upload a specific file:

./nrdiag -attachment-key ATTACHMENT_KEY -file-upload ZIP_FILENAME

Pass command line options

These command line options are available for New Relic Diagnostics:

Option Usage

-a STRING

-attachment-key STRING

Attachment key for automatic upload to a support ticket.

-browser-url STRING

New Relic Diagnostics version 1.1.9 or higher.

This command checks for the presence of the New Relic Browser agent and returns the agent version, the injection method (via APM or via copy/paste), and the Browser loader type (e.g., Pro, Lite, SPA). This can be used to provide detail to New Relic support when troubleshooting intranet sites. Will run only Browser-related Diagnostics checks when invoked.

-c STRING

-config-file STRING

Override default agent configuration file location. Can be used to specify either a folder to search in addition to the default folders, or a path to a specific configuration file.

-file-upload STRING

New Relic Diagnostics version 1.1.8 or higher.

Requires running with -a option. Allows upload of a single file at the path specified. This is in addition to files collected by default.

-filter STRING

Filter task results by result status. Accepts a comma separated list. Accepts: Success, Warning, Failure, Error, None.

-h

-help

Displays full list of options. -help tasks will provide a full list of available tasks.
-output-path STRING Specifies a different directory to write the results (nrdiag-output.zip, nrdiag-output.json and nrdiag-filelist.txt). Default location is ./

-o

-override

Pass in arguments to override. This should only generally be done when requested by New Relic Support.

Example syntax:

-override Java/Config/Agent.Status=Success

-p STRING

-proxy STRING

Provide proxy to be used in HTTP connection tasks. Can be HTTP or HTTPS. Proxy should be in the format https://PROXY_IP:PROXY_PORT. If New Relic Diagnostics finds a proxy in the agent config file, it will use that proxy by default.

-proxy-pw STRING

Proxy password, if necessary. If New Relic Diagnostics finds a proxy in the agent config file, it will use that proxy by default.

-proxy-user STRING

Proxy username, if necessary. If New Relic Diagnostics finds a proxy in the agent config file, it will use that proxy by default.

-t STRING

-tasks STRING

Run only a subset of tasks, either by agent or by task type. You can specify multiple tasks by separating them with commas. For a list of all tasks, run:

./nrdiag -h tasks
-usage-opt-out Decline to send anonymous New Relic Diagnostic tool usage data to New Relic for this run.

-v

-verbose

Display verbose logging during check execution. Disabled by default.

-version

Display current New Relic Diagnostics version. Will also prompt to check for a newer version and prompt to download if a newer version is available.

-y

-yes

Say yes to any prompt that comes up while running. Disabled by default.

Interpret the output

After executing New Relic Diagnostics from your terminal, you will see the results for each task as they are completed. Tasks that result in a Warning or Failure status code will log additional details regarding possible issues found during execution, along with troubleshooting suggestions and relevant links to documentation:

screen-nrdiag-output.png
New Relic Diagnostics outputs any issues it found with your installation, along with troubleshooting suggestions.

File output

New Relic Diagnostics outputs three files:

Diagnostics output files Comments
nrdiag-output.zip A flattened folder structure with one or more config files and any existing New Relic logs. Attach this file to support tickets. This archive also contains a copy of nrdiag-output.json
nrdiag-output.json Output of the individual tests. Attach this output to tickets.
nrdiag-filelist.txt A list of files found. The nrdiag-output.zip file that you attach to support tickets automatically includes this list. You do not need to attach this .txt file separately.

Result status codes

New Relic Diagnostics returns the following status codes after running:

Status code Definition
Success Task successfully executed with no issues detected.
Warning Task successfully executed. However, possible issues detected.
Failure Task failed with issues detected.
Error Task unable to execute. This could be due to a permissions issues.
None Task was determined irrelevant to detected environment and was not executed.

For more help

Recommendations for learning more: