Skip to content

Commit 0ccedff

Browse files
dingsdaxclaude
andcommitted
docs(ruby): Add GoodJob integration documentation
Add comprehensive documentation for the sentry-good_job integration, which adds support for GoodJob (a Postgres-based ActiveJob backend). Key sections: - Installation instructions for Rails and non-Rails applications - Configuration options with code examples - Error capture with enriched context - Performance monitoring with execution time and queue latency - Automatic and manual cron monitoring setup - 5 configuration options (report_after_job_retries, report_only_dead_jobs, include_job_arguments, auto_setup_cron_monitoring, logging_enabled) Based on PR: getsentry/sentry-ruby#2751 Co-Authored-By: Claude <noreply@anthropic.com>
1 parent b57cf2d commit 0ccedff

3 files changed

Lines changed: 233 additions & 0 deletions

File tree

docs/platforms/ruby/common/integrations/index.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ Simply add the relevant gems to your Gemfile and run `bundle install` to install
2121
| <LinkWithPlatformIcon platform="ruby.sidekiq" label="Sidekiq" url="/platforms/ruby/guides/sidekiq" /> | `gem "sentry-sidekiq"` |
2222
| <LinkWithPlatformIcon platform="ruby.delayed_job" label="Delayed Job" url="/platforms/ruby/guides/delayed_job/" /> | `gem "sentry-delayed_job"` |
2323
| <LinkWithPlatformIcon platform="ruby.resque" label="Resque" url="/platforms/ruby/guides/resque" /> | `gem "sentry-resque"` |
24+
| <LinkWithPlatformIcon platform="ruby.good_job" label="GoodJob" url="/platforms/ruby/guides/good_job" /> | `gem "sentry-good_job"` |
2425
| <LinkWithPlatformIcon platform="ruby.opentelemetry" label="OpenTelemetry" url="/platforms/ruby/tracing/instrumentation/opentelemetry" /> | `gem "sentry-opentelemetry"` |
2526

2627
## Patches
Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
title: GoodJob
2+
sdk: "sentry.ruby.good_job"
Lines changed: 230 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
---
2+
title: GoodJob
3+
description: "Learn about using Sentry with GoodJob."
4+
---
5+
6+
The GoodJob integration adds support for [GoodJob](https://github.com/bensheldon/good_job), a Postgres-based ActiveJob backend for Ruby on Rails.
7+
8+
## Install
9+
10+
Install `sentry-good_job` by adding it to your `Gemfile`:
11+
12+
```ruby {filename:Gemfile}
13+
gem "sentry-ruby"
14+
gem "sentry-good_job"
15+
```
16+
17+
Then run:
18+
19+
```bash
20+
bundle install
21+
```
22+
23+
## Configure
24+
25+
### Rails Applications
26+
27+
If you're using Rails, the GoodJob integration will be enabled automatically when you have both `sentry-rails` and `sentry-good_job` in your `Gemfile`. The SDK will be initialized in your Rails application as described in the [Rails integration documentation](/platforms/ruby/guides/rails/#configure).
28+
29+
This example shows how to configure the GoodJob integration with common options:
30+
31+
```ruby {filename:config/initializers/sentry.rb}
32+
Sentry.init do |config|
33+
config.dsn = "___PUBLIC_DSN___"
34+
config.traces_sample_rate = 1.0
35+
36+
# GoodJob integration options
37+
config.good_job.report_after_job_retries = false
38+
config.good_job.include_job_arguments = false
39+
config.good_job.auto_setup_cron_monitoring = true
40+
end
41+
```
42+
43+
### Non-Rails Applications
44+
45+
For non-Rails applications using GoodJob, initialize the Sentry SDK before starting your GoodJob workers:
46+
47+
```ruby
48+
require "sentry-ruby"
49+
require "sentry-good_job"
50+
require "good_job"
51+
52+
Sentry.init do |config|
53+
config.dsn = "___PUBLIC_DSN___"
54+
config.traces_sample_rate = 1.0
55+
end
56+
57+
# Your GoodJob setup
58+
GoodJob.on_thread_error = ->(exception) { Sentry.capture_exception(exception) }
59+
```
60+
61+
## Verify
62+
63+
To verify that the integration is working, create a job that raises an error:
64+
65+
```ruby
66+
class FailingJob < ApplicationJob
67+
queue_as :default
68+
69+
def perform(*args)
70+
1 / 0
71+
end
72+
end
73+
```
74+
75+
Enqueue and process the job:
76+
77+
```ruby
78+
FailingJob.perform_later
79+
```
80+
81+
After the job is processed, you should see the error in [Issues](https://sentry.io/issues/) with enriched context including the job name, queue name, and job ID.
82+
83+
## Behavior
84+
85+
### Error Capture
86+
87+
The GoodJob integration automatically captures exceptions that occur during job execution. Each error event includes:
88+
89+
- Job class name
90+
- Queue name
91+
- Job ID
92+
- Execution attempt number
93+
- Job arguments (if `include_job_arguments` is enabled)
94+
95+
### Performance Monitoring
96+
97+
When performance monitoring is enabled (`traces_sample_rate > 0`), the integration creates spans for each job execution that include:
98+
99+
- Execution time
100+
- Queue latency (time between enqueue and execution)
101+
- Trace propagation from the code that enqueued the job
102+
103+
You can view these spans in [Performance > Traces](https://sentry.io/performance/traces/).
104+
105+
### Trace Propagation
106+
107+
The integration propagates Sentry tracing information from the code that enqueues a job to the job execution. This creates a distributed trace connecting the original request or code to the background job.
108+
109+
## Cron Monitoring
110+
111+
The GoodJob integration includes automatic support for [Cron Monitoring](/product/crons/). If you have cron jobs configured in GoodJob, the integration will automatically set up monitoring for them.
112+
113+
### Automatic Setup
114+
115+
By default, the integration reads your GoodJob cron configuration and automatically creates Sentry cron monitors. This works with GoodJob's cron configuration:
116+
117+
```ruby {filename:config/application.rb}
118+
config.good_job.cron = {
119+
send_daily_reports: {
120+
cron: "0 9 * * *", # Every day at 9am
121+
class: "DailyReportJob"
122+
},
123+
cleanup_old_data: {
124+
cron: "0 2 * * 0", # Every Sunday at 2am
125+
class: "CleanupJob"
126+
}
127+
}
128+
```
129+
130+
With automatic cron monitoring enabled, you'll see these jobs appear in [Crons](https://sentry.io/crons/) with their schedules automatically detected.
131+
132+
### Manual Configuration
133+
134+
You can also manually configure cron monitoring for specific jobs using the `sentry_cron_monitor` method in your job class:
135+
136+
```ruby
137+
class DailyReportJob < ApplicationJob
138+
include Sentry::Cron::MonitorCheckIns
139+
140+
sentry_cron_monitor :daily_reports,
141+
schedule: { type: "crontab", value: "0 9 * * *" },
142+
timezone: "America/New_York"
143+
144+
def perform
145+
# Generate and send reports
146+
end
147+
end
148+
```
149+
150+
This approach gives you fine-grained control over monitoring settings including custom monitor slugs and timezone specifications.
151+
152+
## Options
153+
154+
The following options are available for the GoodJob integration. Set them in your `Sentry.init` block:
155+
156+
### `report_after_job_retries`
157+
158+
Only report errors to Sentry after all retry attempts have been exhausted.
159+
160+
**Type:** `Boolean`
161+
**Default:** `false`
162+
163+
```ruby
164+
config.good_job.report_after_job_retries = true
165+
```
166+
167+
When enabled, errors from jobs that will be retried are not sent to Sentry until the final retry fails.
168+
169+
### `report_only_dead_jobs`
170+
171+
Only report errors from jobs that cannot be retried (dead jobs).
172+
173+
**Type:** `Boolean`
174+
**Default:** `false`
175+
176+
```ruby
177+
config.good_job.report_only_dead_jobs = true
178+
```
179+
180+
This is useful if you only want to be notified about jobs that have permanently failed.
181+
182+
### `include_job_arguments`
183+
184+
Include job arguments in error context.
185+
186+
**Type:** `Boolean`
187+
**Default:** `false`
188+
189+
```ruby
190+
config.good_job.include_job_arguments = true
191+
```
192+
193+
<Alert level="warning">
194+
195+
Job arguments may contain sensitive data. Only enable this option if you're confident that your job arguments don't contain personally identifiable information (PII) or other sensitive data. Consider using [`before_send`](/platforms/ruby/configuration/filtering/) to filter sensitive arguments before they're sent to Sentry.
196+
197+
</Alert>
198+
199+
### `auto_setup_cron_monitoring`
200+
201+
Automatically set up cron monitoring by reading GoodJob's cron configuration.
202+
203+
**Type:** `Boolean`
204+
**Default:** `true`
205+
206+
```ruby
207+
config.good_job.auto_setup_cron_monitoring = false
208+
```
209+
210+
Set this to `false` if you want to manually configure cron monitoring for your scheduled jobs.
211+
212+
### `logging_enabled`
213+
214+
Enable detailed logging for debugging the integration.
215+
216+
**Type:** `Boolean`
217+
**Default:** `false`
218+
219+
```ruby
220+
config.good_job.logging_enabled = true
221+
```
222+
223+
When enabled, the integration will log additional information about job processing, error capture, and cron monitoring setup. This is useful for troubleshooting but not recommended for production.
224+
225+
## Supported Versions
226+
227+
- Ruby: 2.4+
228+
- Rails: 5.2+
229+
- GoodJob: 3.0+
230+
- Sentry Ruby SDK: 5.28.0+

0 commit comments

Comments
 (0)