Menu

AppSignal for Node.js: Diagnose tool

The AppSignal Node.js package ships with a self-diagnostic tool. This tool can be used to debug your AppSignal installation and is one of the first things our support team asks for when there's an issue.

The diagnostic report

This command-line tool is useful when testing AppSignal on a system and validating the local configuration. It outputs useful information to debug issues and it checks if AppSignal agent can run on the machine's architecture and communicate with the AppSignal servers.

This diagnostic tool collects and outputs the following:

  • information about the AppSignal package.
  • information about the host system and Node.js.
  • if the AppSignal extension and agent can run on the host system.
  • all configured config options (including default values).
  • if the configuration is valid and active.
  • if the Push API key is present and valid (internet connection required).
  • where configuration option values originate from.

Read more about how to use the diagnose command on the Debugging page.

Submitting the report

You need to pass the --send-report option to send the diagnose report to AppSignal. If used, the report will be send to our servers and you will receive a support token.

When you send this support token to us we will review the report and help you debug the issue. We've seen that copy-pasting the report output usually loses formatting and makes it harder to read, which is why it's sent to our servers in the JSON format.

Usage

On the command line in your project (a directory with a package.json and @appsignal/nodejs installed) run:

Shell
npx @appsignal/cli diagnose

At the very least, the APPSIGNAL_PUSH_API_KEY must be set before the diagnose command can be run. If this isn't set in your environment already, you can also set it at runtime with the --api-key option:

Shell
npx @appsignal/cli diagnose --api-key="<PUSH API KEY HERE>"

You can also set the environment variable at runtime:

Shell
APPSIGNAL_PUSH_API_KEY="<PUSH API KEY HERE>" npx @appsignal/cli diagnose

To run the diagnose on your production server, and send the report to AppSignal for support purposes, you can run the following command:

Shell
npx @appsignal/cli diagnose --environment=production --send-report --api-key="<PUSH API KEY HERE>"

The environment option is useful when the default environment is not the one you want to diagnose. The diagnose tool will warn you when no environment is selected.

Options

OptionDescription
--environment=<environment>Set the environment to use in the command, e.g. production or staging.
--api-keyDefine which API key to use.
--[no-]send-reportAutomatically send, or do not send the report.

Environment option

Define which app environment AppSignal should load in the diagnose CLI.

Shell
npx @appsignal/cli diagnose --environment=production

Report submission option

The options to submit the report immediately, or not, were added to the AppSignal Node.js package version 1.2.5.

Submit the report to AppSignal:

Shell
npx @appsignal/cli diagnose --send-report

Do not submit the report to AppSignal:

Shell
npx @appsignal/cli diagnose --no-send-report

Configuration output format

Configuration option values format

The configuration options are printed to the CLI as their inspected values. This means we print them as Node.js would in a console.

  • Strings values are printed with double quotes around them, e.g. "My app name".
  • Booleans values are printed as their raw values: true and false.
  • Arrays values are printed as a collection of values surrounded by square brackets, e.g. ["HTTP_ACCEPT", "HTTP_ACCEPT_CHARSET"].
    • Empty Arrays are printed as two square brackets: [].
  • Null or undefined values are printed as null or undefined.