Ruby troubleshooting

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

Before you spend too much time in 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 Ruby supported versions.

Check the installation steps.

Validate that the Installation steps were properly followed.

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

You can validate by viewing gem "instana" in the application Gemfile and viewing mentions of instana in the Gemfile.lock file. Alternatively, from the Ruby application directory, you can run bundle exec gem list. This command lists all the Ruby gems in the application bundle. Validate that the Instana Ruby gem is in that list.

Assure that the Instana gem is the latest version.

The latest version that is released can be found on RubyGems. In the Gemfile.lock, you must see the latest version of the Instana Ruby gem noted alongside the name, such as instana (x.x.x).

Validate that Instana is mentioned in the application log output.

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

Enable debug output and recheck 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 whether any Instana related error messages exists.

Check Instana host agent logs for any messages that are related to this Ruby process.

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

To boot, see the Testing in your application section. Pay special attention to see whether any Instana-related error messages appear in the Ruby application output.

File a support ticket.

If you validated all the preceding steps and the Ruby process still doesn't show up in the Instana dashboard, open a support case for further investigation.

The support ticket must include:

1. Environment details: Platform, Ruby version, and frameworks in use
2. Summary of all the preceding validations.

Check whether your application framework is supported.

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

Check whether the ::Instana::Rack middleware is 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 the following command:

bundle exec rake middleware

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

Check whether you are 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.

Enable debug output and recheck 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 whether any Instana-related error messages appear.

From an application console, generate a custom trace.

If all else fails, you can open an application console and run the following command 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 must see the following line in the application logs:

Instana:: Reporting 1 spans

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

Check Instana host agent logs for any messages that are related to this Ruby process.

File a support ticket.

If you validated all the steps and Ruby traces are still not visible in the Instana dashboard, file a Support ticket for further investigate.

The support ticket must include:

1. Environment details: Platform, Ruby version, and frameworks in use
2. Summary of all the preceding validations.

Ensure that the agent has enough resources to process the requests

If you took 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.

Disable process lookup

You can also disable a "fast path" for the agent by adding the following to the agent configuration. This configuration can reduce the resources that are consumed by the agent, but might 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 that use fork as a concurrency primitive with short-lived child processes.

com.instana.processlookup:
  enabled: false