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

AutoProfile™

Edit online

AutoProfile generates and reports process profiles to Instana automatically and continuously. Learn more about profiles in Analyze Profiles section.

For more information about enabling it, see Configuring profiling.

Host agent communication

Edit online

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'

Kubernetes and Red Hat OpenShift

Edit online

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

Edit online

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

Edit online

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

Edit online

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

Edit online

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

Edit online

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.

Puma

Edit online

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

Edit online

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

Edit online

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

Edit online

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

Edit online

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.

Debugging and more verbosity

Edit online

You can set the Instana Ruby gem's debugging configuration.

Environment variable

Edit online

Setting INSTANA_DEBUG to a non-nil value enables additional logging output generally useful for development and troubleshooting.

AWS Fargate

Edit online

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

AWS Lambda

Edit online

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

Span filtering

Edit online

You can use this feature to filter out unnecessary traces or calls to reduce the overall data ingestion. For example, you can filter the tracing of specific Redis methods, such as redis.get.

This feature is available for Redis only with Instana Ruby gem version 2.1.0 or higher. Currently, the Ruby gem only supports filtering for Redis operations.

Filtering rules

Edit online

Use the following rules for filtering spans:

When a span is filtered, all subsequent downstream spans are also filtered (suppression).
Use the wildcard * to filter all Redis methods.
Method names might vary depending on the programming language and technology. Refer to the Instana UI to determine the correct method for your Redis operations.

Note: The span filtering feature works with only exact method names. Ensure that you use the correct method name to be filtered.

Configuring span filtering

Edit online

You can configure span filtering for Redis by using any of the following options:

Environment variables
Configuration file
Agent configuration

Note: If more than one approach is used at the same time, Ruby gem prioritizes in the following order: environment variables, configuration file, and agent configuration.

Environment variables for span filtering

Edit online

You can configure span filtering using the following environment variables:

INSTANA_CONFIG_PATH : Specify the path to a YAML configuration file
INSTANA_TRACING_FILTER_<policy>_<name>_ATTRIBUTES=<rule> : Define filter rules directly

Using `INSTANA_CONFIG_PATH`

Edit online

With this environment variable, you can configure filtering through an external YAML file:

INSTANA_CONFIG_PATH=/path/to/config.yaml

YAML configuration for span filtering

Edit online

The YAML configuration file supports two formats:

Format 1: Simple Redis filtering

tracing:
  filter:
      exclude:
        - name: "Redis Operations"
          attributes:
            - key: "type"
              values: ["redis"]

This configuration filters all spans for Redis.

Format 2: Advanced attribute-based filtering

tracing:
  filter:
    deactivate: false  # Optional, defaults to false
    exclude:
      - name: "Redis Operations"
        suppression: true  # Optional, defaults to true
        attributes:
          - key: "category"
            values: ["databases"]
          - key: "type"
            values: ["redis"]
            match_type: "strict"  # Optional, defaults to "strict"

This configuration filters all Redis spans.

For Redis filtering, the key attribute can be:

category: Technology category (databases)
type: Library (redis)
Redis-specific attributes (redis.command)

The match_type can be:

strict: Exact match (default)
startswith: String starts with the value
endswith: String ends with the value
contains: String contains the value

Using environment variables for direct configuration

Edit online

You can define filter rules directly using environment variables:

# Filter all Redis operations
INSTANA_TRACING_FILTER_EXCLUDE_REDIS_ATTRIBUTES="type;redis;strict"

# Filter specific Redis commands
INSTANA_TRACING_FILTER_EXCLUDE_REDIS_ATTRIBUTES="redis.command;get,set;strict"

The format for rules is: key;values;match_type where:

key: The attribute to check
values: Comma-separated list of values to match
match_type: Optional matching strategy (defaults to strict)

Multiple rules can be combined with the pipe character:

INSTANA_TRACING_FILTER_EXCLUDE_REDIS_ATTRIBUTES="type;redis;strict|redis.command;get,set;strict"

Agent configuration for span filtering

Edit online

To configure span filtering using the agent configuration approach, add the filter configuration to the agent's configuration.yaml file. For more information, see the Span filtering section.

Examples

Edit online

Example 1: Filter all Redis operations

tracing:
  filter:
    exclude:
      - name: "Redis Operations"
        attributes:
          - key: "type"
            values: ["redis"]

Example 2: Filter specific Redis commands

tracing:
  filter:
    exclude:
      - name: "Redis GET and SET"
        attributes:
          - key: "type"
            values: ["redis"]
          - key: "redis.command"
            values: ["get", "set"]

Example 3: Filter Redis operations with pattern matching

tracing:
  filter:
    exclude:
      - name: "Redis GET operations"
        attributes:
          - key: "redis.command"
            values: ["get"]
            match_type: "startswith"

This will filter Redis commands that start with get (for example, get, and set).

Configuring span disabling

Edit online

You can disable spans by using the span filtering feature of the Instana Ruby Tracer.

With the span disabling feature, you can completely disable the generation of spans in your application. This feature can be useful in the following scenarios:

You want to reduce the volume of spans generated by your application.
You have operations that are not relevant for monitoring.
You want to focus on other parts of your application's performance.

Supported categories

Edit online

There are several categories of operations that can be filtered.

Categories are sets of libraries grouped by a common type of technology or protocol. You can disable spans for the following categories:

logging
databases

Configuration options

Edit online

You can disable spans by using one of the following options:

Option 1: Using YAML configuration

Edit online

Create a YAML configuration file and set the INSTANA_CONFIG_PATH environment variable to point to a package as shown in the following example:

tracing:
  disable:
    - redis: true

The disable key can receive a list of category or type names. A type name is the reference for any framework, library name, or instrumentation name supported by the Instana Ruby Tracer.

Individual type configurations take precedence over their parent category settings, regardless of the definition order. This approach allows granular control where specific instrumentations can remain enabled even when their broader category is disabled.

The following configuration example disables all database spans, except those for Redis:

tracing:
  disable:
    - databases: true
    - redis: false

Option 2: Using environment variables

Edit online

You can use the INSTANA_TRACING_DISABLE environment variable:

# Disable only Redis spans
INSTANA_TRACING_DISABLE=redis

# Disable all database spans (including Redis)
INSTANA_TRACING_DISABLE=databases

# Disable multiple technologies
INSTANA_TRACING_DISABLE=redis,databases

Option 3: Programmatically

Edit online

You can also disable Redis spans programmatically:

# Disable Redis spans
Instana.config[:redis][:enabled] = false

# Disable logging category
Instana.config[:logging][:enabled] = false

Option 4: Agent configuration

Edit online

To disable Redis spans using the agent configuration approach, add the disable configuration to the agent's configuration.yaml file:

tracing:
  disable:
    - databases: true

To disable the databases category spans by using the agent configuration approach, use the following category configuration in the agent configuration.yaml file:

For more information, see the Agent Configuration section.

Edit online

Ruby configuration: Configuring the Instana gem

Global enable or disable

AutoProfile™

Host agent communication

Kubernetes and Red Hat OpenShift

Enabling or disabling individual components

Enable or disable backtrace collection

Setting a custom service name

Setting the process name

Forking webservers and job processing systems

Puma

Unicorn

Rack middleware

Managing the agent background thread

Logging

Debugging and more verbosity

Environment variable

AWS Fargate

AWS Lambda

Span filtering

Filtering rules

Configuring span filtering

Environment variables for span filtering

Using INSTANA_CONFIG_PATH

YAML configuration for span filtering

Using environment variables for direct configuration

Agent configuration for span filtering

Examples

Configuring span disabling

Supported categories

Configuration options

Option 1: Using YAML configuration

Option 2: Using environment variables

Option 3: Programmatically

Option 4: Agent configuration

Related topics

Using `INSTANA_CONFIG_PATH`