Ruby configuration: Configuring the Instana gem

Global enable or disable

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

export INSTANA_DISABLE=true

Other global enable or disable options are:

Instana.config[:tracing][:enabled] # default true

If you want 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 through IP 127.0.0.1 and as a fallback through the host's default gateway for containerized environments. If the agent is not available at either of these locations, you can use environment variables to configure where to look for the Instana host agent.

The environment variables must 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 and Red Hat OpenShift

Ensure that your instrumented applications contact the Instana host agent. For more information, see Configure network access for monitored applications.

Enabling or disabling individual components

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

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 or disable backtrace collection

Because backtraces are 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 configuration in-turn enables 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 must add a configuration to notify the Instana agent that a fork occurred.

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

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

Rack middleware

This gem detects and automagically inserts 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 configuration:

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 creates a lightweight background thread to periodically collect and report metrics and traces. By default, this uses a standard Ruby thread. If you want to have greater control and potentially boot the agent that is reporting manually in an alternative thread system (such as actor-based threads), you can do so with the following configuration:

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

Then, in the background thread of your choice, call:

::Instana.agent.start

This call is blocking. It kicks off a loop of timers that periodically collects and reports metrics and trace data. This call must be called only 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, or info 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 inherits and uses the Ruby on Rails logger when Rails is in use.

AWS Fargate

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

AWS Lambda

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

Related topics

• Ruby overview
• Ruby configuration
• Ruby Tracing SDK
• Ruby OpenTracing
• OpenTracing best practices
• Ruby troubleshooting
• Ruby supported versions
• Ruby GitHub repository