Ruby Configuration - Configuring the Instana gem
TABLE OF CONTENTS
- Global Enable/Disable
- Host Agent Communication
- Kubernetes & OpenShift
- Enabling/Disabling Individual Components
- Enable/Disable Backtrace Collection
- Setting a Custom Service Name
- Rack Middleware
- Managing the Agent Background Thread
- See Also
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:
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'
Please see this document on assuring that your instrumented applications can contact the Instana Host Agent.
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
Instrumentation can be disabled as:
::Instana.config[:excon][:enabled] = false ::Instana.config[:rack][:enabled] = false
For a full list of instrumentation, see config.rb
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.
You can set a custom service name for your application by setting the
INSTANA_SERVICE_NAME environment variable:
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.
For the Puma webserver, add the following to your
on_worker_boot do ::Instana.agent.after_fork if defined?(::Instana) end
For Unicorn in forking mode, add the following block to your
after_fork do |server, worker| ::Instana.agent.after_fork if defined?(::Instana) end
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.
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:
Thread.new do ::Instana.agent.start end
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.
INSTANA_DEBUG to a non nil value will enable extra logging output generally useful for development and troubleshooting.