Ruby Configuration - Configuring the Instana gem

Global Enable/Disable

The entire gem can be disabled at runtime by setting an environment variable for your application:


Other global enable/disable options are:

# Enable/Disable tracing
Instana.config[:tracing][:enabled] # default true

If you wish to disable the built-in instrumentation but still permit custom instrumentation, set the following environment variable for your application:


Host Agent Communication

The sensor tries to communicate with the Instana agent via IP and as a fallback via the host’s default gateway for containerized environments. Should the agent not be available at either of these locations, you can use environment variables to configure where to look for the Instana Host Agent.

The environment variables should be set in the environment of the running process.

export INSTANA_AGENT_PORT = '42699'

See also the General Reference: Environment Variables for Language Sensors

Kubernetes & OpenShift

Please see this document on assuring that your instrumented applications can contact the Instana Host Agent.

Enabling/Disabling Individual Components

Individual components can be enabled and disabled with a local config.

To disable a single component in the gem, you can disable a single component with the following code in an initializer for your application:

::Instana.config[:metrics][:gc][:enabled] = false

Current metric components are :gc, :memory and :thread.

Instrumentation can be disabled as:

::Instana.config[:excon][:enabled] = false
::Instana.config[:rack][:enabled] = false

For a full list of instrumentation, see config.rb

Enable/Disable Backtrace Collection

Because backtraces are somewhat expensive in Ruby, backtrace collection is disabled by default but can be enabled with the following code in an initializer for your application:

::Instana.config[:collect_backtraces] = true

This will in-turn enable CodeView in your dashboard to get code level insights.

Setting a Custom Service Name

You can set a custom service name for your application by setting the INSTANA_SERVICE_NAME environment variable:


See also the General Reference: Environment Variables for Language Sensors

Forking Webservers and Job Processing Systems

For software packages such as Puma, Resque or others that fork to perform work, you should add a configuration to notify the Instana agent that a fork occured.


For the Puma webserver, add the following to your puma.rb configuration:

on_worker_boot do
  ::Instana.agent.after_fork if defined?(::Instana)


For Unicorn in forking mode, add the following block to your unicorn.rb file:

after_fork do |server, worker|
  ::Instana.agent.after_fork if defined?(::Instana)

Rack Middleware

This gem will detect and automagically insert the Instana Rack middleware into the middleware stack when a supported framework is present. We are currently adding support for more frameworks. If you are using a yet to be instrumented framework, you can insert the Instana Rack middleware with the following:

require "instana/rack"
config.middleware.use ::Instana::Rack

…or whatever specific middleware call is appropriate for your framework.

Managing the Agent Background Thread

This agent spawns a lightweight background thread to periodically collect and report metrics and traces. Be default, this uses a standard Ruby thread. If you wish to have greater control and potentially boot the agent reporting manually in an alternative thread system (such as actor based threads), you can do so with the following:

gem "instana", :require => "instana/setup"

…then in the background thread of your choice simply call:


Note that this call is blocking. It kicks off a loop of timers that periodically collects and reports metrics and trace data. This should only be called from inside an already initialized background thread: do


The Instana logger is a standard Ruby logger that logs debug, warn, info (etc.) messages and can be set as follows:

require "logger"
::Instana.logger.level = ::Logger::WARN

The gem can be configured to use your application logger instead:

::Instana.logger = ::My.logger

By default, the Instana gem will inherit and use the Ruby on Rails logger when Rails is in use.

Debugging & More Verbosity

Environment Variable

Setting INSTANA_DEBUG to a non nil value will enable extra logging output generally useful for development and troubleshooting.

See also the General Reference: Environment Variables for Language Sensors

See Also