Ruby Troubleshooting

The Instana gem has been designed to be fully automatic but if something goes wrong, please file a ticket and let us know! We love to hear feedback (good or bad) so we can continually improve.

The following page outlines some steps you can take to potentially diagnose any issues that may arise.

Supported Components

Before spending too much time diagnosing an issue, first make sure that the component and environment in question is supported. A list of all supported components can be found in the Ruby Supported Versions page.

Problem Areas

Ruby Process doesn’t show up in dashboard

1. Validate that your environment is supported and you are running a supported version of Ruby

Before spending too much time diagnosing an issue, first make sure that the component and environment in question is supported. A list of all supported components can be found in the Ruby Supported Versions page.

2. Validate the Install steps

Validate that the Installation steps were properly followed.

3. Validate that the Instana Ruby gem is installed in the application bundle

This can be validated by seeing gem "instana" in the application Gemfile and seeing mentions of instana in the Gemfile.lock file.

Alternatively, from the Ruby application directory, you can run bundle exec gem list. This will list all of the Ruby gems in the application bundle. Validate that the Instana Ruby gem is in that list.

4. Assure that the Instana gem is the latest version.

The latest version released can be found on Rubygems.

In the Gemfile.lock, you should see the latest version of the Instana Ruby gem noted alongside the name such as instana (x.x.x).

5. Validate that Instana is mentioned in the application log output.

Application and/or container logs should always have a boot message similar to Stan is on the scene. Starting Instana instrumentation version x.x.x

6. Enable debug output and re-check application or container logs.

Set the environment variable INSTANA_DEBUG=true for the Ruby process and revalidate the application or container logs (same as #3).

Pay special attention to see if there are any Instana related error messages.

7. Check Instana Host Agent logs for any messages related to this Ruby process.

8. Try booting the Ruby application in verbose mode from a console

See here on how to do this. Pay special attention to see if there are any Instana related error messages in the Ruby application output.

9. File a Support Ticket.

If you validated all of the above and the Ruby process still doesn’t show up in the Instana dashboard, please file a Support Ticket so that we can investigate further.

The support ticket should include:

  1. Environment details; platform, Ruby version, frameworks in use
  2. Summary of all of the above validations.

Logging & Environment Variables

By default, the gem will only log messages that indicate if any problems are encountered. If you want a more verbose logging output, set the INSTANA_DEBUG environment variable. It enables Debug level logging in the Instana gem.

instana console output

In the example above, you can see that the host agent isn’t available (either because it isn’t running or wasn’t installed). Once the host agent is available, the Instana gem will automatically re-connect without any intervention.

There are even more methods to control logging output. See the Ruby Configuration page for more details.

Testing in your Application

To diagnose the Instana gem from your application, often simply opening an application console with verbose logging can be enough to identify issues:

rails console

In the example above, you can see the Instana Ruby gem initialize, instrument some components and a success notification: Host agent available. We're in business.

Disabling Individual Components

If a particular part of the gem (such as instrumentation) is causing problems for you, you can temporarily avoid the issue by disabling just that component. See the Ruby Configuration page on how to enable and disable individual components.

See Also