DOCSEARCHbyAlgolia
Submit Docs

Sentry Ruby SDK

repository·master·Indexed 21 days ago

https://github.com/getsentry/sentry-ruby

The Sentry SDK for Ruby provides error capturing and performance monitoring for Ruby 2.4 through 4.0 and JRuby 9.0. It includes official integrations for Rails, Sidekiq, Resque, DelayedJob, Yabeda, and OpenTelemetry. The SDK supports distributed tracing via sentry-opentelemetry and provides a Sentry::Integrable module for developers to create custom extensions.

Tokens
18.3K
Snippets
72
Records
102
Agent score
76%

What's inside sentry-ruby

  1. How sentry-yabeda handles metrics

    master

    The sentry-yabeda integration automatically forwards Yabeda metrics to Sentry.

    Metric Mapping

    • Counters, Histograms, and Gauges (directly-set) are forwarded to Sentry inline when called.
    • Summaries are mapped to Sentry distributions, as Sentry does not have a native summary type.

    Collector Blocks and Background Collection

    In Prometheus, Yabeda collector blocks (Yabeda.configure { collect { ... } }) are pull-based and triggered by scrapes. Because Sentry is push-based, sentry-yabeda manages this by running a background thread that calls Yabeda.collect! every 15 seconds.

    Note: Metrics populated via collector blocks (such as GC stats or thread counts) will not carry trace context.

  2. Enable Performance Monitoring in Rails

    master

    You can activate performance monitoring by setting a sampling strategy in the Sentry.init block. You have two primary ways to control sampling:

    1. Uniform Sample Rate: Set config.traces_sample_rate to a float between 0.0 and 1.0 to apply the same sampling rate to all transactions.
    2. Dynamic Sampling: Set config.traces_sampler to a lambda to implement custom logic. The lambda receives a sampling_context containing:
      • sampling_context[:transaction_context]: Information about the transaction.
      • sampling_context[:parent_sampled]: The parent transaction's sample decision.

    The lambda should return a boolean or a float between 0.0 and 1.0.

    Sentry.init do |config|
  # set a uniform sample rate between 0.0 and 1.0
  config.traces_sample_rate = 0.2

  # or control sampling dynamically
  config.traces_sampler = lambda do |sampling_context|
    # sampling_context[:transaction_context] contains the information about the transaction
    # sampling_context[:parent_sampled] contains the transaction's parent's sample decision
    true # return value can be a boolean or a float between 0.0 and 1.0
  end
end

  3. Install the Sentry Sidekiq integration

    master

    To integrate Sentry with Sidekiq, add both sentry-ruby and sentry-sidekiq to your Gemfile. Once installed, sentry-sidekiq automatically configures a custom middleware and error handler to capture exceptions occurring within your Sidekiq workers.

    gem "sentry-ruby"
gem "sentry-sidekiq"

  4. Create a Sentry Ruby extension using Sentry::Integrable

    master

    If you are building a gem that provides integration support for sentry-ruby, you can use the Sentry::Integrable module to simplify the process.

    To use Sentry::Integrable, follow these requirements:

    1. Separate Requirement: You must explicitly require "sentry/integrable".
    2. Namespace: Your extension's module or class must be defined under the Sentry namespace.
    3. Extend: Your module must extend Integrable.
    4. Registration: Call register_integration with a name and version to register it with the SDK core.

    When registered, Sentry::Integrable automatically:

    • Generates .capture_exception and .capture_message methods on your module (e.g., Sentry::YourExtension.capture_exception).
    • Generates SDK metadata for the extension (e.g., {name: "sentry.ruby.your_extension", version: "1.0.0"}).

    Important: Always use the generated helpers (capture_exception and capture_message) for integration-level events. These helpers inject { integration: "integration_name" } into event hints, allowing users to identify the source in before_send callbacks and ensuring the event carries the correct integration metadata.

    require "sentry-ruby"

# 1. The integrable module needs to be required separately
require "sentry/integrable" 

module Sentry
  # 2. The module/class of the extension should be defined under the Sentry namespace
  module MyExtension 
    
    # 3. Extend the module
    extend Integrable 
    
    # 4. Use the register_integration method to register your extension to the SDK core
    register_integration name: "my_extension", version: "1.0.0"
  end
end

# Usage of generated helpers:
Sentry::MyExtension.capture_exception(StandardError.new("Something went wrong"))

  5. Install sentry-opentelemetry

    master

    To use Sentry with OpenTelemetry in a Ruby application, add the following gems to your Gemfile. You will need the core Sentry gems, the sentry-opentelemetry integration, and the standard OpenTelemetry SDK and instrumentations.

    gem "sentry-ruby"
gem "sentry-rails"
gem "sentry-opentelemetry"

gem "opentelemetry-sdk"
gem "opentelemetry-instrumentation-all"

  6. Install the Sentry DelayedJob integration

    master

    To integrate Sentry with DelayedJob, add both sentry-ruby and sentry-delayed_job to your Gemfile. Once installed, sentry-delayed_job automatically configures a custom middleware and error handler to capture exceptions occurring within your DelayedJob workers.

    gem "sentry-ruby"
gem "sentry-delayed_job"

  7. Configure OpenTelemetry with Sentry Span Processor and Propagator

    master

    After configuring Sentry, you must set up the OpenTelemetry SDK to use the Sentry span processor and propagator. This ensures that spans generated by OpenTelemetry are correctly processed and sent to Sentry, and that trace context is propagated across services.

    # config/initializers/otel.rb

OpenTelemetry::SDK.configure do |c|
  c.use_all
  c.add_span_processor(Sentry::OpenTelemetry::SpanProcessor.instance)
end

OpenTelemetry.propagation = Sentry::OpenTelemetry::Propagator.new

  8. Configure the Sentry SDK

    master

    Initialize and configure the Sentry SDK using Sentry.init. At a minimum, you must provide your Sentry DSN (Data Source Name) to route events to your Sentry project.

    require "sentry-ruby"

Sentry.init do |config|
  config.dsn = "MY_DSN"
end

  9. Install the Sentry SDK for Ruby

    master

    To get started with Sentry, add the core sentry-ruby gem to your project. Depending on your application stack, you should also install the relevant integration gems to enable automatic error capturing and instrumentation for specific frameworks or background workers.

    # Core SDK
gem "sentry-ruby"

# Optional integrations
gem "sentry-rails"
gem "sentry-sidekiq"
gem "sentry-delayed_job"
gem "sentry-resque"
gem "sentry-opentelemetry"
gem "sentry-yabeda"

  11. Install and configure sentry-yabeda

    master

    To use Yabeda metrics with Sentry, add both sentry-ruby and sentry-yabeda to your Gemfile. You must explicitly enable metrics in your Sentry initialization block using config.enable_metrics = true for the integration to function.

    gem "sentry-ruby"
gem "sentry-yabeda"
    Sentry.init do |config|
  config.dsn = ENV["SENTRY_DSN"]
  config.enable_metrics = true
end