Monitoring Ruby

Edit online

With Instana Observability, you can monitor your Ruby applications comprehensively to identify bottlenecks and optimize performance.

To begin, install the Instana host agent in your environment. Then, add the instana gem to your application. The gem automatically collects metrics and traces from your Ruby instances that you can view in the Instana UI.

The instana gem provides automated code instrumentation for supported technologies, zero configuration health monitoring of Ruby instances, and end-to-end traces of requests across all systems.

Runtime metrics

Edit online

The instana gem collects the following runtime metrics from your Ruby instances:

  • Ruby Version
  • Runtime Arguments
  • Framework
  • Gem Bundle
  • Time Spent in GC
  • Memory Usage
  • Heap Slots
  • Threads

Installation

Edit online

The instana gem is available on Rubygems. To install, add this line to the end of your application's Gemfile:

gem 'instana'

And then execute:

bundle

Or install it yourself as:

gem install instana
Note: If you encounter Bundler::HTTPError Could not fetch specs from # https://rubygems.org/ or Gem::RemoteFetcher::UnknownHostError timed out error when you run the bundle command, then try to disable IPv6 to fix the error.

Tracer logs

Edit online

At require time, the library will output:

Stan is on the scene.  Starting Instana instrumentation version X.X.X.

Once the agent has made a connection to the host agent, it will output:

Host agent available. We're in business.

Other log messages may appear and indicate an error state. Refer to the Troubleshooting section for more details.

Platforms

Edit online

You can monitor Ruby applications with Instana on the following platforms:

Kubernetes

Edit online

The Instana AutoTrace webhook is an implementation of a Kubernetes Mutating webhook Admission Controller that automatically sets up everything that is required to monitor Ruby applications with Instana, across an entire Kubernetes cluster.

If you elect to install the Instana AutoTrace webhook on your Kubernetes clusters, you have no need to perform any manual step to trace any of your Ruby applications running in those clusters.

For Kubernetes (and other container based deployments), the Instana Ruby gem requires an ip binary available (such as from the iproute2 OS package). This requirement will be removed in a future version.

Configuration

Edit online

Although the gem has no configuration required for out of the box metrics and distributed tracing, individual components can be configured as needed. See the Ruby configuration page for more information.

Troubleshooting

Edit online

You can encounter the following issues when you monitor Ruby applications with Instana:

Ruby sensor not installed

Edit online

Monitoring issue type: ruby_sensor_not_installed

The Instana AutoTrace webhook is not installed and the Ruby process does not include the instana Ruby gem, or the Ruby sensor cannot communicate with the Instana host agent.

To activate the Instana monitoring for Ruby, refer to the Installation section. If you are sure that either the Instana AutoTrace webhook or the Ruby gem is correctly installed, troubleshoot this issue by following the steps in Ruby Process doesn't show up in dashboard for the Instana Ruby sensor.

Verify the process is instrumented

Edit online

If you are using the Instana AutoTrace webhook and the Ruby sensor is active, you can see the following line in your application's logs:

AutoTracing for Ruby is starting on version #<version>

If you do not see this line in your application's logs, then the setup is not correct. For more information about the correct setup, see Instana AutoTrace webhook.

If you are doing manual instrumentation, make sure that the instana gem is installed in your application and is active. If the Ruby sensor is active, you will see the following entries in your application's logs:

Stan is on the scene.  Starting Instana instrumentation version #<version>

If you do not see this log, then the setup is not correct. Please refer to the Installation documentation.

If you see this log message, then it is very likely a network connectivity issue with the host agent, see the next section.

Verify the tracer can connect to the host agent

Edit online

If the Ruby tracer is installed (refer to he previous section), verify that the Ruby process can connect to the host agent on the same host on port 42699. For more information on the required network visibility, refer to the Network requirements documentation for the Instana host agent.

What we see increasingly often, is that in containerized platforms either there are network visibility issues between the container with the application to be traced and the container of the Instana host agent; another issue of the same kind, due to some overlay network setup, the container of the application to be traced does not connect to the Instana agent container on the same host.

Often the problem is that the Ruby tracer is using the wrong ip address or DNS name to talk to the Instana agent. You can instruct the Ruby tracer to user a specific network address via the INSTANA_AGENT_HOST environment-variable.

In very few cases, we have seen customers that set up their networking so that the problem was not the network address, but the port the tracer uses. In case you need a port remapping, because the host agent does not listen on port 42699 but something else, you can instruct the tracer to use a different port via the INSTANA_AGENT_PORT environment variable.

If these troubleshooting steps didn't help you, open a Support ticket.

Interactions with other instrumentation and monitoring libraries

Edit online

As of the 194 release, the instana gem uses prepend instead of alias chaining to allow it to work along side of instrumentation and monitoring libraries. This means that if multiple libraries prepend their instrumentation to a target method, the instrumentation will fire sequence.

If you need to explicitly alias-chain a method that is instrumented by the instana gem or you are using a library that does the alias chaining for you, then the explicit alias-chaining or the loading of the library that does the alias chaining, needs to happen after the instana gem is loaded. Otherwise, the instana instrumentation doesn't function.