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:

export INSTANA_DISABLE=true

Other global enable/disable options are:

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:

export INSTANA_DISABLE_AUTO_INSTR=true

Host Agent Communication

The sensor tries to communicate with the Instana agent via IP 127.0.0.1 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_HOST = '127.0.0.1'
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:

export INSTANA_SERVICE_NAME=my-custom-service-name

For more information about configuring a custom service, see Setting the service name globally.

Setting the Process Name

Use the environment variable INSTANA_PROCESS_NAME to set a custom label for the infrastructure entity that represents the Ruby process.

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

Puma

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

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

Unicorn

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)
end

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:

::Instana.agent.start

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:

Thread.new do
  ::Instana.agent.start
end

Logging

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

AWS Fargate

When running inside of an AWS Lambda function, the Ruby library follows our standard configuration options.

AWS Lambda

When running inside of an AWS Lambda function, the Ruby library follows our standard configuration options.

See Also