AppSignal for Ruby: Diagnose tool

The AppSignal Ruby gem includes a self-diagnostic tool that can be used to debug the installation and configuration of your AppSignal integration. It is one of the first tools that our support team requests you to run when debugging an issue.

The diagnostic report

You can use this diagnostic tool to test and validate your AppSignal installation. It outputs useful information to debug issues and it checks if AppSignal agent is able to run on the machine's architecture and communicate with the AppSignal servers.

This diagnostic tool collects and outputs the following:

• Information about the AppSignal gem.
• Information about the host system and Ruby.
• 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.
• If the required system paths exist, are writable, and which user and group are owners.
• Small parts of the tail from the available log files.

You can read more about how to use the diagnose command in our Debugging documentation.

Submitting the report

In gem version 2.2.0 and higher you will be prompted to send the report to AppSignal. If accepted 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 send to our servers in the JSON format.

In gem version 2.8.0 the option was added to view the report yourself on AppSignal.com. A link to the report is printed in the diagnose output. This web view will also show any validation problems and warnings our system detected.

Usage

On the command-line in your project run:

appsignal diagnose

If you're experiencing an issue in production and need to send the report to AppSignal for support, you can run the following command to generate and send the report to our servers:

bundle exec appsignal diagnose --environment=production --send-report

Options

Environment option

To select a specific environment with the CLI, run the below command:

appsignal diagnose --environment=production

The environment option is useful when there is no default environment (non-Rails apps and apps configured with an config file) or the default environment is not the one you want to diagnose. The diagnose tool will warn you when no environment is selected.

Report submission option

The options to submit the report immediately, or not, were added to the AppSignal gem version 2.8.0. Selecting whether or not to send the report with these options will no longer prompt this question, making it easier to use in non-interactive environments.

To run diagnose and submit the report data to AppSignal, run the below command:

appsignal diagnose --send-report

To run diagnose without sending the report data to AppSignal, run the below command:

appsignal 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 Ruby 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: [].
• Nil values are printed as nil.

Configuration sources

The configuration section also displays the origin of config option values, which can help identify sources that override values defined in other config sources.

You can read more about configuration sources their load order, and priority in the configuration load order documentation.

The configuration options are displayed based on the source of their values and the number of sources that set them, like in the below example:

Configuration
  # Option with a value loaded only from the default source
  send_params: true

  # Option with one source
  # A different source than the default source
  name: "My app name" (Loaded from file)

  # Option with multiple sources
  # Listed in order of priority (highest priority last)
  active: true
    Sources:
      default: false
      file:    false
      env:     true