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.

Compatibility

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

  • New Relic APM: Java, .NET (both Framework and Core), Node.js, PHP, Python, and Ruby agents
  • New Relic Browser: Browser agent detection
  • New Relic Infrastructure: Linux and Windows agents
  • New Relic Mobile: iOS and Android 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. Download the latest version, which contains executable files for Linux, macOS, and Windows.
  2. Move the executable for your platform into the location of the agent's root directory, which depends on the New Relic agent.
  3. Recommendation: Temporarily raise the logging level for the New Relic agent you are troubleshooting.
  4. Run the executable.

New Relic Diagnostics automatically searches its root directory and subdirectories for agent configuration files and other relevant data.

Refer to these detailed procedures for each platform:

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

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

For 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 a ticket attachment key.

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

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

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.

To upload your results automatically to a New Relic Support ticket, include the ticket's attachment key by using the -attachment-key command line flag:

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

To view your attachment key from support.newrelic.com:

  1. Log in to support.newrelic.com/login.
  2. From the menu bar, click the user dropdown, then select Inbox.
  3. Select your ticket from the list.
  4. Copy the NR Diagnostics attachment key that appears at the top of the ticket.

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

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

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