From 2a8af49b71513b99dfc5d58865c0d49c760f2e75 Mon Sep 17 00:00:00 2001 From: Neel Shah Date: Fri, 16 Aug 2024 14:46:03 +0200 Subject: [PATCH] feat(ruby): Document integrations - gems and patches --- .../ruby/common/configuration/options.mdx | 20 ++++- .../ruby/common/integrations/index.mdx | 79 +++++++++++++++++++ .../breadcrumbs/breadcrumbs-example/ruby.mdx | 20 ----- 3 files changed, 98 insertions(+), 21 deletions(-) create mode 100644 docs/platforms/ruby/common/integrations/index.mdx diff --git a/docs/platforms/ruby/common/configuration/options.mdx b/docs/platforms/ruby/common/configuration/options.mdx index 9f387648402ca..46eb773c5b653 100644 --- a/docs/platforms/ruby/common/configuration/options.mdx +++ b/docs/platforms/ruby/common/configuration/options.mdx @@ -191,6 +191,24 @@ config.inspect_exception_causes_for_exclusion = true + + +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]`. + +```ruby +# enable :faraday patch +config.enabled_patches << :faraday + +# disable :puma patch +config.enabled_patches.delete(:puma) +``` + + + Determine whether to ignore exceptions caused by rake integrations. The default is `false`. @@ -223,7 +241,7 @@ To disable all tracing, you'll either need to set -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). +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 must be defined to enable tracing. diff --git a/docs/platforms/ruby/common/integrations/index.mdx b/docs/platforms/ruby/common/integrations/index.mdx new file mode 100644 index 0000000000000..cfa05262ecb58 --- /dev/null +++ b/docs/platforms/ruby/common/integrations/index.mdx @@ -0,0 +1,79 @@ +--- +title: Integrations +description: "Sentry provides additional integrations designed to change configuration or add instrumentation to your application." +sidebar_order: 40 +--- + +The Sentry SDK uses integrations to hook into the functionality of popular frameworks and libraries to automatically instrument your application and give you the best data out of the box. + +Some of our integrations are available as separate gems while others are available as patches that can be enabled from the `sentry-ruby` gem. You can find an overview of all available integrations below. + +## Gems + +The following table lists all integrations available as gems. + +Simply add the relevant gems to your Gemfile and run `bundle install` to install them. + +| Integration | `Gemfile` | +| --------------------------------------------------------------------------------------------------------------------- | :--------------: | +| | `gem "sentry-rails"` | +| | `gem "sentry-sidekiq"` | +| | `gem "sentry-delayed_job"` | +| | `gem "sentry-resque"` | +| | `gem "sentry-opentelemetry"` | + +## Patches + +The following table lists all integrations available as patches and which ones are enabled by default. + +You can use [`config.enabled_patches`](/platforms/ruby/configuration/options/#enabled-patches) to enable or disable them. + +```ruby +# enable :faraday patch +config.enabled_patches << :faraday + +# disable :puma patch +config.enabled_patches.delete(:puma) +``` + +| Patch | **Auto-enabled** | +| ----------------------------|:----------------:| +| `:http` | ✓ | +| `:redis` | ✓ | +| `:puma` | ✓ | +| `:faraday` | | +| `:graphql` | | + +## Features + +### Rails + +The Rails integration is a feature rich integration that: + +* captures Errors anywhere in your Rails application +* creates Transactions for incoming HTTP Requests +* records Spans in those Transactions for various important operations like: + * database queries (performed with `activerecord`) + * view renders + +### Queues + +The various Queue integrations for Sidekiq, Delayed Job and Resque create distributed traces connecting tasks that are performed in the background asynchronously. + +The Rails integration also includes this functionality for `ActiveJob`. + +### OpenTelemetry + +The OpenTelemetry integration is used for exporting spans instrumented by an OpenTelemetry SDK into Sentry. See the [OpenTelemetry Setup](/platforms/ruby/tracing/instrumentation/opentelemetry) instructions for more details. + +### HTTP Requests + +Outgoing HTTP Requests are instrumented as Spans by the `:http` (for requests done with `Net::HTTP`) and `:faraday` patches. + +### GraphQL + +GraphQL operations are instrumented as Spans by the `:graphql` patch. + +### Puma + +The `:puma` patch captures low level exceptions outside your application stack. diff --git a/platform-includes/enriching-events/breadcrumbs/breadcrumbs-example/ruby.mdx b/platform-includes/enriching-events/breadcrumbs/breadcrumbs-example/ruby.mdx index a1eb6d7808995..bccc6f62b7b23 100644 --- a/platform-includes/enriching-events/breadcrumbs/breadcrumbs-example/ruby.mdx +++ b/platform-includes/enriching-events/breadcrumbs/breadcrumbs-example/ruby.mdx @@ -6,23 +6,3 @@ crumb = Sentry::Breadcrumb.new( ) Sentry.add_breadcrumb(crumb) ``` - -Appropriate places to inject Breadcrumbs may be places like your HTTP library: - -```ruby -# Instrumenting Faraday with a middleware: - -class SentryFaradayMiddleware - def call - # Add a breadcrumb every time we complete an HTTP request - @app.call(request_env).on_complete do |response_env| - crumb = Sentry::Breadcrumb.new( - data: { response_env: response_env }, - category: "faraday", - message: "Completed request to #{request_env[:url]}" - ) - Sentry.add_breadcrumb(crumb) - end - end -end -```