Basic Options

SDKs are configurable using a variety of options. The options are largely standardized among SDKs, but there are some differences to better accommodate platform peculiarities. Options are set when the SDK is first initialized.

Options are passed as attributes to the config object within the init block:

Sentry.init do |config|
  config.dsn = 'https://examplePublicKey@o0.ingest.sentry.io/0'
  config.max_breadcrumbs = 5
  config.debug = true
end

Common Options

The below is a list of common options across SDKs. They work more or less the same in all SDKs with a few subtle differences to better support different platforms. Options that can be read from an environment variable (SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_RELEASE) will be read automatically.

dsn

The DSN tells the SDK where to send events. If this value isn't provided, the SDK will try to read it from the SENTRY_DSN environment variable. If that variable doesn't exist, the SDK won't send any events.

Learn more about DSN utilization.

debug

This turns debug mode on or off. When enabled, SDK errors will be logged with backtrace. If you want more output, use config.logger.level. debug only works for attaching backtraces to the messages.

logger

The logger used by Sentry. The default for Rails is Rails.logger, otherwise it's Sentry::Logger. Make sure to change the logger level if you need debug output. We don't recommend doing this in production unless absolutely necessary.

config.logger = Sentry::Logger.new(STDOUT)
config.logger.level = ::Logger::DEBUG # defaults to INFO

release

Lets you track your application version in Sentry.

We intelligently guess the release in the following order of preference:

• The SENTRY_RELEASE environment variable
• Commit SHA of the last commit (git)
• Reading from the REVISION file in the app root (used by Capistrano)
• Heroku’s dyno metadata via the HEROKU_SLUG_COMMIT environment variable (must have been enabled via Heroku Labs)

Sentry.init do |config|
  #...
  config.release = 'my-project-name@2.3.12'
end

sample_rate

The sampling factor to apply to events. A value of 0.00 won't send any events, and a value of 1.00 will send 100% of events.

# send 50% of events
config.sample_rate = 0.5

send_client_reports

This lets you attach diagnostic client reports about dropped events to an existing envelope max once every 30s. The default is true. If you don't want to send this data, opt-out by setting:

config.send_client_reports = false

<Note>
This information isn't currently visible to users, but we're planning on adding it to the user-facing UI in the near future.
</Note>

send_default_pii

When its value is false (the default), sensitive information like:

• user ip
• user cookie
• request body
• query string in the url

won't be sent to Sentry. You can re-enable it by setting:

config.send_default_pii = true

send_modules

A boolean to decide whether to send module (dependency) information to Sentry. The default is true.

config.send_modules = false # if you don't want to send all the dependency info

include_local_variables

Whether to capture local variables from the raised exceptions frame. The default is false. (In older versions, this was called capture_exception_frame_locals.)

max_breadcrumbs

The maximum number of breadcrumbs the SDK could hold. The default is 100.

config.max_breadcrumbs = 30

breadcrumbs_logger

Sentry supports different breadcrumbs loggers in the Ruby SDK:

• :sentry_logger - A general breadcrumbs logger for all Ruby applications.
• :http_logger - Captures requests made with the standard net/http library.
• :redis_logger - Captures breadcrumbs from redis operations.
• :active_support_logger - Built on top of ActiveSupport instrumentation and provides many Rails-specific information.
• :monotonic_active_support_logger - Similar to :active_support_logger but breadcrumbs will have monotonic time values. Only available with Rails 6.1+.

And you can enable them with the breadcrumbs_logger option:

config.breadcrumbs_logger = [:active_support_logger]
config.breadcrumbs_logger = [:active_support_logger, :http_logger]

context_lines

How many lines to display before/after the line where issue occurs. Default is 3.

environment

Sets the environment. This string is freeform and not set by default. A release can be associated with more than one environment so that you can separate them in the UI (think staging vs prod or similar).

Sentry automatically sets the current environment from the environment variables: SENTRY_CURRENT_ENV, SENTRY_ENVIRONMENT, RAILS_ENV, RACK_ENV in that order and defaults to development.

Sentry.init do |config|
  #...
  config.environment = 'production'
end

enabled_environments

By default, events will be sent to Sentry in all environments. If you don't want to send events in a specific environment, you can unset the SENTRY_DSN variable in that environment.

You can also set up Sentry to only run in certain environments by configuring the enabled_environments list. For example, to only run Sentry in production:

config.enabled_environments = %w[production]

excluded_exceptions

You can use this option to stop getting notifications about certain exceptions. In the example below, the exceptions Rails uses to generate 404 responses will be suppressed.

config.excluded_exceptions += ['ActionController::RoutingError', 'ActiveRecord::RecordNotFound']

You can find the list of exceptions that are excluded by default in Sentry::Configuration::IGNORE_DEFAULT. It is suggested that you append to these defaults rather than overwrite them with =.

inspect_exception_causes_for_exclusion

Inspect an incoming exception's causes when determining whether or not that exception should be excluded. This option works together with excluded_exceptions. The default value is true.

config.inspect_exception_causes_for_exclusion = true

enabled_patches

Some of our integrations work via patches that need to be enabled. Use this option to control which patches are loaded when the SDK is initialized.

The list of all available patches is: [:http, :redis, :puma, :graphql, :faraday].

The list of patches enabled by default is: [:http, :redis, :puma].

# enable :faraday patch
config.enabled_patches << :faraday

# disable :puma patch
config.enabled_patches.delete(:puma)

skip_rake_integration

Determine whether to ignore exceptions caused by rake integrations. The default is false.

trusted_proxies

These trusted proxies will be skipped when the SDK computes the user's ip address and sentry-rails will automatically inject the value of Rails.application.config.action_dispatch.trusted_proxies to this option.

config.trusted_proxies = ["2.2.2.2"]

Tracing Options

traces_sample_rate

A number between 0 and 1 that determines the percentage of total transaction that will be sent to Sentry (with 0 representing 0% and 1, 100%). This will apply equally to all transactions created in the app. Either this or traces_sampler must be defined to enable tracing.

If traces_sample_rate is set to 0, no new traces will be created. However, if you have another service (for example a JS frontend) that makes requests to your service and has trace information, those traces will be continued and transactions will be sent to Sentry.

To disable all tracing, you'll either need to set traces_sample_rate=None or set enable_tracing=False. Once this is done, no new traces will be started and no incoming traces will be continued.

Sentry.init do |config|
  # ...
  config.traces_sample_rate = 0.2
end

traces_sampler

A lambda or proc that's responsible for determining the chance that a given transaction has of being sent to Sentry (from 0-100%). It will automatically be passed information about the transaction and the context in which it's being created, and must return a number between 0 (0% chance of being sent) and 1 (100% chance of being sent).

It can also be used for filtering transactions, by returning 0 for those that are of no interest. Either this or traces_sample_rate must be defined to enable tracing.

Sentry.init do |config|
  #...
  config.traces_sampler = lambda do |sampling_context|
    # if this is the continuation of a trace, just use that decision (rate controlled by the caller)
    unless sampling_context[:parent_sampled].nil?
      next sampling_context[:parent_sampled]
    end

    # the sampling context also has the full rack environment if you want to check the path directly
    rack_env = sampling_context[:env]
    return 0.0 if rack_env && rack_env['PATH_INFO'] =~ /health_check/

    # transaction_context is the transaction object in hash form
    # keep in mind that sampling happens right after the transaction is initialized
    # for example, at the beginning of the request
    transaction_context = sampling_context[:transaction_context]

    # transaction_context helps you sample transactions with more sophistication
    # for example, you can provide different sample rates based on the operation or name
    op = transaction_context[:op]
    transaction_name = transaction_context[:name]

    case op
    when /http/
      # for Rails applications, transaction_name would be the request's path (env["PATH_INFO"]) instead of "Controller#action"
      case transaction_name
      when /health_check/
        0.0
      when /payment/
        0.5
      when /api/
        0.2
      else
        0.1
      end
    when /sidekiq/
      0.01 # you may want to set a lower rate for background jobs if the number is large
    else
      0.0 # ignore all other transactions
    end
  end
end

enable_backpressure_handling

A boolean (the default is false) that controls whether a new monitor thread will be spawned to perform health checks on the SDK. If the system is unhealthy, the SDK will keep halving the traces_sample_rate set by you in 10 second intervals until recovery. This downsampling helps ensure that the system stays stable and reduces SDK overhead under high load.

trace_propagation_targets

An optional property that controls which downstream services receive tracing data, in the form of a sentry-trace and a baggage header attached to any outgoing HTTP requests.

The option may contain an array of strings or regex against which the URLs of outgoing requests are matched. If one of the entries in the list matches the URL of an outgoing request, trace headers will be attached to that request. String entries don't have to be full matches, (meaning the URL of a request is matched when it contains a string provided through the option).

By default, trace headers are attached to every outgoing request from the instrumented client.

propagate_traces

By default, Sentry injects sentry-trace and baggage headers to outgoing requests made with Net::HTTP to connect traces between services. You can disable this behavior with:

config.propagate_traces = false

Hooks

The below options can be used to hook the SDK in various ways and customize how events are being reported.

before_send

Provides a lambda or proc that's called with an SDK-specific message or error event object, and can return a modified event object, or nil to skip reporting the event. This can be used, for instance, for manual PII stripping before sending.

By the time before_send is executed, all scope data has already been applied to the event. Further modification of the scope won't have any effect.

Sentry.init do |config|
  #...

  # this example uses Rails' parameter filter to sanitize the event payload
  # for Rails 6+
  filter = ActiveSupport::ParameterFilter.new(Rails.application.config.filter_parameters)
  # for Rails 5
  filter = ActionDispatch::Http::ParameterFilter.new(Rails.application.config.filter_parameters)
  config.before_send = lambda do |event, hint|
    filter.filter(event.to_hash)
  end
end

before_send_transaction

Provides a lambda or proc that's called with an SDK-specific transaction event object, and can return a modified transaction event object, or nil to skip reporting the event. One way this might be used is for manual PII stripping before sending.

Sentry.init do |config|
  # ...
  config.before_send_transaction = lambda do |event, _hint|
    # skip unimportant transactions
    if event.transaction == "/unimportant/healthcheck/route"
      # don't send the event to Sentry
      nil
    else
      # filter out SQL queries from spans with sensitive data
      event.spans.each do |span|
        span[:description] = '<FILTERED>' if span[:op].start_with?('db')
      end

      event
    end
  end
end

backtrace_cleanup_callback

If you want to clean up the backtrace of an exception before it's sent to Sentry, you can specify a callback with backtrace_cleanup_callback, for example:

config.backtrace_cleanup_callback = lambda do |backtrace|
  Rails.backtrace_cleaner.clean(backtrace)
end

Sentry.init do |config|
  # ...
  config.before_send_transaction = lambda do |event, _hint|
    # skip unimportant transactions
    if event.transaction == "/unimportant/healthcheck/route"
      # don't send the event to Sentry
      nil
    else
      # filter out SQL queries from spans with sensitive data
      event.spans.each do |span|
        span[:description] = '<FILTERED>' if span[:op].start_with?('db')
      end

      event
    end
  end
end

Transport Options

background_worker_threads

Sentry will send events in a non-blocking way with its own background worker. By default, the worker holds a thread pool that has the number of available processors threads. But you can override it as follows:

config.background_worker_threads = 5

Or if you want to send events synchronously, set the value to 0:

config.background_worker_threads = 0

transport_class

By default, the SDK uses the Sentry::HTTPTransport class for sending events to Sentry, which should work for the majority of users. But if you want to use your own Transport class, you can change it with this option:

config.transport.transport_class = MyTransportClass

It would generally be advisable to derive your custom transport class from Sentry::HTTPTransport and just override the necessary logic.

proxy

Setup a proxy to use to connect to Sentry. This option is respected by the default Sentry::HTTPTransport class. You can set config.transport.proxy with as a String containing a proxy URI, or a URI object, or a Hash containing uri, user and password keys.

Sentry.init do |config|
  # ...

  # Provide proxy config as a String
  config.transport.proxy = "http://user:password@proxyhost.net:8080"

  # Or a URI
  config.transport.proxy = URI("http://user:password@proxyhost.net:8080")

  # Or a Hash
  config.transport.proxy = {
    uri: "http://proxyhost.net:8080",
    user: "user",
    password: "password"
  }
end