From 9aeaacb276c9e2526d1d490115fda2a561cf72f3 Mon Sep 17 00:00:00 2001 From: Neel Shah Date: Fri, 16 Aug 2024 13:35:48 +0200 Subject: [PATCH] chore(ruby): Update common options to match other platforms (#11091) * chore(ruby): Update common options to match other platforms * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Update docs/platforms/ruby/common/configuration/options.mdx Co-authored-by: Liza Mock * Apply suggestions from code review Co-authored-by: Liza Mock --------- Co-authored-by: Liza Mock --- .../ruby/common/configuration/options.mdx | 336 ++++++++++-------- .../configuration/config-intro/ruby.mdx | 5 +- 2 files changed, 194 insertions(+), 147 deletions(-) diff --git a/docs/platforms/ruby/common/configuration/options.mdx b/docs/platforms/ruby/common/configuration/options.mdx index 854558e86186d..9f387648402ca 100644 --- a/docs/platforms/ruby/common/configuration/options.mdx +++ b/docs/platforms/ruby/common/configuration/options.mdx @@ -1,74 +1,136 @@ --- title: Basic Options sidebar_order: 1 -description: "Learn more about how to configure the SDK." +description: "Learn more about configuration options for the SDK. These options are set when the SDK is first initialized and passed to the init function as an object." --- -Configuration is passed as part of the client initialization: +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. - + + +## 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. + + + +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](/product/sentry-basics/dsn-explainer/#dsn-utilization). + + + + + +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. + + + + + +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.** ```ruby -Sentry.init do |config| - config.dsn = '___PUBLIC_DSN___' - config.attr = 'value' -end +config.logger = Sentry::Logger.new(STDOUT) +config.logger.level = ::Logger::DEBUG # defaults to INFO ``` -## Optional settings + + + -`async` +Lets you track your application version in Sentry. -**This option has been deprecated and could be removed in the future.** +We intelligently guess the release in the following order of preference: -**For more information, please read [this issue](https://github.com/getsentry/sentry-ruby/issues/1522).** +- 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) -By default, `sentry-ruby` sends events asynchronously with its own background worker. This option only exists for compatibility reasons, and it's not recommended to new Sentry users. + -`background_worker_threads` + -If `config.async` isn't provided, 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 processors] threads. But you can configure it with this configuration option: + + +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. ```ruby -config.background_worker_threads = 5 +# send 50% of events +config.sample_rate = 0.5 ``` -Or if you want to send events synchronously, set the value to 0: + + + + +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: ```ruby -config.background_worker_threads = 0 +config.send_client_reports = false + + +This information isn't currently visible to users, but we're planning on adding it to the user-facing UI in the near future. + +``` + + + + + +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: + +```ruby +config.send_default_pii = true ``` -`backtrace_cleanup_callback` + + + -If you want to clean up exceptions' backtrace before it's sent to Sentry, you can specify a callback with `backtrace_cleanup_callback` to do that. For example: +A boolean to decide whether to send module (dependency) information to Sentry. The default is `true`. ```ruby -config.backtrace_cleanup_callback = lambda do |backtrace| - Rails.backtrace_cleaner.clean(backtrace) -end +config.send_modules = false # if you don't want to send all the dependency info ``` -`before_send` + -Provide a lambda or proc. This will be `called` before sending an error event to Sentry. Receives an `event` and `hint` as parameter. `hint` is a dict `{:exception => ex | nil, :message => message | nil}`. It is possible to mutate the event, also if this function returns `nil` the event will be dropped and not sent. + - +Whether to capture local variables from the raised exceptions frame. The default is `false`. (In older versions, this was called `capture_exception_frame_locals`.) -`before_send_transaction` + -Provide a lambda or proc. This will be `called` before sending a transaction event to Sentry. It receives an `event` and `hint` as a parameter. The `hint` object is currently empty, but might be augmented in the future. It's possible to mutate the event. Also, if this function returns `nil`, the event will be dropped and not sent. + - +The maximum number of breadcrumbs the SDK could hold. The default is `100`. -`breadcrumbs_logger` +```ruby +config.max_breadcrumbs = 30 +``` + + + + 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](https://guides.rubyonrails.org/active_support_instrumentation.html) 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+. -- `:http_logger` - It captures requests made with the standard `net/http` library. And you can enable them with the `breadcrumbs_logger` option: @@ -77,39 +139,39 @@ config.breadcrumbs_logger = [:active_support_logger] config.breadcrumbs_logger = [:active_support_logger, :http_logger] ``` -`include_local_variables` - -Whether to capture local variables from the raised exception's frame. Default is `false`. This was called `capture_exception_frame_locals` in older versions. + -`context_lines` + How many lines to display before/after the line where issue occurs. Default is `3`. -`debug` + -Activation of debugging mode. When enabled, SDK errors will be logged with backtrace. Default is `false`. Please use `config.logger.level` for more output; this is merely for attaching backtraces to the messages. + -`enabled_environments` +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). -As of v0.10.0, events will be sent to Sentry in all environments. If you do not wish to send events in an environment, we suggest you unset the SENTRY_DSN variable in that environment. +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`. -Alternately, you can configure Sentry to run only in certain environments by configuring the `enabled_environments` list. For example, to only run Sentry in production: + -```ruby -config.enabled_environments = %w[production] -``` + -`environment` + -Sentry automatically sets the current environment to RAILS_ENV, or if it is not present, RACK_ENV. If you are using Sentry outside of Rack or Rails, or wish to override environment detection, you’ll need to set the current environment by setting SENTRY_CURRENT_ENV or configuring the client yourself: +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: + +```ruby +config.enabled_environments = %w[production] +``` -`excluded_exceptions` + -If you never wish to be notified of certain exceptions, specify ‘excluded_exceptions’ in your config file. + -In the example below, the exceptions Rails uses to generate 404 responses will be suppressed. +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. ```ruby config.excluded_exceptions += ['ActionController::RoutingError', 'ActiveRecord::RecordNotFound'] @@ -117,153 +179,153 @@ config.excluded_exceptions += ['ActionController::RoutingError', 'ActiveRecord:: 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`. Default value is `true`. + + +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`. ```ruby config.inspect_exception_causes_for_exclusion = true ``` -`logger` + -The logger used by Sentry. Default is `Rails.logger` in Rails, otherwise an instance of `Sentry::Logger`. Make sure to change the logger level if you need debug output. + -```ruby -config.logger = Sentry::Logger.new(STDOUT) -config.logger.level = ::Logger::DEBUG # defaults to INFO -``` +Determine whether to ignore exceptions caused by rake integrations. The default is `false`. + + -`max_breadcrumbs` + -The maximum number of breadcrumbs the SDK would hold. Default is `100`. +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. ```ruby -config.max_breadcrumbs = 30 +config.trusted_proxies = ["2.2.2.2"] ``` -`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. +## Tracing Options -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 do not 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. +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 must be defined to enable tracing. -`propagate_traces` +If 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. -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 +To disable all tracing, you'll either need to set `=None` or set `=False`. Once this is done, no new traces will be started and no incoming traces will be continued. -```ruby -config.propagate_traces = false -``` + -`release` + -Track the version of your application in Sentry. + -We guess the release intelligently in the following order of preference: +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). -- Commit SHA of the last commit (git) -- Reading from the REVISION file in the app root -- Heroku’s dyno metadata (must have enabled via Heroku Labs) +It can also be used for filtering transactions, by returning 0 for those that are of no interest. Either this or must be defined to enable tracing. - + -`sample_rate` + -The sampling factor to apply to events. A value of 0.00 will deny sending any events, and a value of 1.00 will send 100% of events. + -```ruby -# send 50% of events -config.sample_rate = 0.5 -``` +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. -`send_client_reports` + -Attach diagnostic client reports about dropped events to an existing envelope max once every 30s. Default is `true`. + -This information will not be visible to users at the moment, but we're planning to add this information to user-facing UI. +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. -If you **do not** want to send this data, you can opt-out by setting +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. + + + + + +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: ```ruby -config.send_client_reports = false +config.propagate_traces = false ``` -`send_default_pii` + -When its value is `false` (default), sensitive information like +## Hooks -- user ip -- user cookie -- request body -- query string in the url +The below options can be used to hook the SDK in various ways and customize how events are being reported. -will not be sent to Sentry. + -You can re-enable it by setting: +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. -```ruby -config.send_default_pii = true -``` +By the time is executed, all scope data has already been applied to the event. Further modification of the scope won't have any effect. -`send_modules` + -A boolean to decide whether to send modules (dependencies) information to Sentry (default is `true`). + -```ruby -config.send_modules = false # if you don't want to send all the dependency info -``` + + +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. -`skip_rake_integration` + -Determine whether to ignore exceptions caused by rake integrations. Default is `false`. + -`trusted_proxies` + -These trusted proxies will be skipped when the SDK computing the user's ip address. `sentry-rails` will automatically inject the value of `Rails.application.config.action_dispatch.trusted_proxie` to this option. +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: ```ruby -config.trusted_proxies = ["2.2.2.2"] +config.backtrace_cleanup_callback = lambda do |backtrace| + Rails.backtrace_cleaner.clean(backtrace) +end ``` -## Tracing Options - -`traces_sample_rate` + -By providing a float between `0.0` and `1.0`, you can control the sampling factor of tracing events. + -- `nil` (default) or `0.0` means the tracing feature is disabled. -- `1.0` means sending all the events. - - - -`traces_sampler` +## Transport Options -You can gain more control on tracing event (transaction)'s sampling decision by providing a callable object (`Proc` or `Lambda`) as a `traces_sampler`: + - +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](https://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent.html#available_processor_count-class_method) threads. But you can override it as follows: -`enable_backpressure_handling` +```ruby +config.background_worker_threads = 5 +``` -A boolean 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. +Or if you want to send events synchronously, set the value to 0: -This option is disabled by default. +```ruby +config.background_worker_threads = 0 +``` -## Transport Options + -`transport_class` + -By default, the SDK uses `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: +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: ```ruby config.transport.transport_class = MyTransportClass ``` -`proxy` +It would generally be advisable to derive your custom transport class from `Sentry::HTTPTransport` and just override the necessary logic. + + + + 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. @@ -284,22 +346,6 @@ Sentry.init do |config| password: "password" } end - ``` -## Environment Variables - -`SENTRY_DSN` - -After you complete setting up a project, you’ll be given a value which we call a DSN, or Data Source Name. It looks a lot like a standard URL, but it’s actually just a representation of the configuration required by Sentry (the Sentry client). It consists of a few pieces, including the protocol, public and secret keys, the server address, and the project identifier. - -With Sentry, you may either set the SENTRY_DSN environment variable (recommended), or set your DSN manually in a config block: - - - -```ruby -# in Rails, this might be in config/initializers/sentry.rb -Sentry.init do |config| - config.dsn = '___PUBLIC_DSN___' -end -``` + diff --git a/platform-includes/configuration/config-intro/ruby.mdx b/platform-includes/configuration/config-intro/ruby.mdx index a17aaf9f2f7f3..9f6011e252893 100644 --- a/platform-includes/configuration/config-intro/ruby.mdx +++ b/platform-includes/configuration/config-intro/ruby.mdx @@ -1,10 +1,11 @@ -Options are passed within the `init` block: +Options are passed as attributes to the `config` object within the `init` block: ```ruby Sentry.init do |config| config.dsn = '___PUBLIC_DSN___' - config.context_lines = 5 + config.max_breadcrumbs = 5 + config.debug = true end ```