|
| 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