Ruby Troubleshooting

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, open a support case 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.

No Traces for the Ruby Application

If your Instana Ruby application is on your Instana dashboard but no traces seem to be coming from the application, check the following:

1. Is your application framework supported?

Check that the components in use in your Ruby application are supported.

2. Is the ::Instana::Rack middleware active?

If you are using a Rack based framework such as Ruby on Rails, make sure that the ::Instana::Rack middleware is properly installed as middleware. Under normal circumstances, this middleware is installed automatically for various frameworks.

To validate in Ruby on Rails you can run:

bundle exec rake middleware

You should see an entry for ::Instana::Rack. If you have to, you can install it manually.

3. Are you late loading the Instana gem with require => false in the Gemfile?

Late loading the Instana Ruby gem is not encouraged as boot processes in various stacks are often strict and order dependent. A common symptom of late loading is the lack of the ::Instana::Rack Rack middleware which is what initiates tracing of incoming requests.

If, for some reason, you still prefer to late load the Instana Ruby gem, then make sure to follow the manual instructions (if needed) on installing the Instana Rack middleware

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

5. From an application console, generate a custom trace

If all else fails, you can open an application console and execute the following to generate a custom trace:

require "instana"

Instana::Tracer.start_or_continue_trace(:my_custom_trace) do
  sleep 1
end

On success and enabled debug output (described in the previous step), you should see the following in the application logs:

Instana:: Reporting 1 spans

Then check your Instana dashboard (under Query Analyze for a call.span_type of SDK). You should see a trace named "my_custom_trace".

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

7. File a Support Ticket.

If you validated all the above and Ruby traces are still not visible in the Instana dashboard, 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.

High Agent CPU Usage in Containerized Environments

In containerized environments with Ruby processes which make use of fork as a concurrency primitive, the agent can become overloaded trying to track the newly created processes.

1. Ensure The Agent Has Enough Resources To Process The Requests

   If you have taken steps to limit the amount of CPU and memory needed by the agent, ensure that the limits in place provide enough resources for the agent to be able to complete all of its required tasks.

2. Disable Process Lookup

   You can also disable a "fast path" for the agent by adding the following to the agent configuration. This can reduce the resources consumed by the agent, but may lead to traces being dropped if the process exits before it's able to send any data to the agent. This issue is generally present for applications which use fork as a concurrecny primitive with short lived child processes.

   com.instana.processlookup:
     enabled: false