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.

New Relic Diagnostics - Ubuntu Linux
New Relic Diagnostics running on Ubuntu Linux. nrdiag checks the configuration of your agents for issues and can generate zipped troubleshooting logs, ready to be attached to support tickets.

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

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 your application's root directory.
  4. Recommendation: Temporarily raise the logging level for the New Relic agent for more accurate troubleshooting. Note that changing the logging level requires you to restart your application.
  5. Run the executable.
    • Recommendation: Run with a task suite (CLI option) to scope your troubleshooting.

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 application's root directory.
  4. Run nrdiag (along with any CLI options and/or a ticket attachment key):

    ./nrdiag CLI_OPTIONS

New Relic Diagnostics outputs issues it discovers to your terminal. If it doesn't, then include an attachment key as a CLI option. This will add relevant files to your support ticket for troubleshooting.

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 application'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.

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 application's 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 the latest version of New Relic Diagnostics. If necessary, manually download the latest version.

  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.

Suites flag (highly recommended CLI option)

A suite is a collection of health checks that target specific products or issues. Using a suite can help narrow the scope of troubleshooting and reduce the occurrence of false positives.

View suites

To review a list of available suites, run New Relic Diagnostics with the -help suites option.

./nrdiag --help suites

Run suites

Suites are run by providing the -suites flag and one or more suite names (for example, java) to run as arguments.

System Command line flag
Linux, macOS

For 32-bit systems:

./nrdiag --suites SUITE NAMES

For 64-bit systems:

./nrdiag_x64 --suites SUITE NAMES
Windows

To run from PowerShell, add ./ to the start of cmd.

For 32-bit systems:

nrdiag.exe --suites SUITE NAMES

For 64-bit systems:

nrdiag_x64.exe --suites SUITE NAMES

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.

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, follow the manual upload process.

System Command line flag
Linux, macOS, Synthetics private minion
./nrdiag -attachment-key ATTACHMENT_KEY
Windows

To run from PowerShell, add ./ to the start of cmd.

For 32-bit systems:

nrdiag.exe -attachment-key ATTACHMENT_KEY

For 64-bit systems:

nrdiag_x64.exe -attachment-key ATTACHMENT_KEY

Manual upload

If you modified or inspected the content of nrdiag-output.zip and want 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

When invoked, this will only run Browser-related Diagnostics checks.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 (Pro, Lite, SPA). This can be used to provide detail to New Relic Support when troubleshooting intranet sites.

-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.

-s STRING

--suites STRING

Run a suite, a collection of tasks that target specific products or issues. You can specify multiple suites by separating them with commas. For a list of all suites, run:

./nrdiag -h suites

-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.

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. New Relic Diagnostics inspects system information and New Relic product artifacts (logs, config files) that are relevant for performing diagnostic checks that assess New Relic product configuration and operability.

By default, this data is not transmitted to New Relic. You do have the option to upload this information to a support ticket over HTTPS.

Data uploaded to support tickets

Diagnostics does allow uploading of this information to a support ticket over HTTPS, with the use of a specific command-line argument. You will be prompted before collection of any files that we expect to have a likelihood of containing sensitive information.

Before the collected files contained within nrdiag-output.zip are uploaded to New Relic, you will also be prompted. This allows you to review and edit any information that you do not want to provide. (For example, the nrdiag-output.zip will include your user name.) You also have the option to cancel the upload altogether.

Data storage

Any support ticket attachments made using Diagnostics or containing Diagnostics data that are less than or equal to 20MB are stored by Zendesk. Otherwise these attachments are stored by New Relic. For more information, see Zendesk's privacy and data protection policies.

Environment variables

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.

  • 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

For more information about New Relic's security measures, see our security and privacy documentation, or visit the New Relic security website.

For more help

Recommendations for learning more: