|
| 1 | +## Job Monitoring |
| 2 | + |
| 3 | +If you're using [Oban](https://github.com/sorentwo/oban) or [Quantum](https://github.com/quantum-elixir/quantum-core), Sentry can automatically capture check-ins for all jobs that are scheduled to run periodically. To achieve this, you need to enable the corresponding Sentry plugin: |
| 4 | + |
| 5 | +```elixir |
| 6 | +config :sentry, |
| 7 | + integrations: [ |
| 8 | + oban: [cron: [enabled: true]], |
| 9 | + # Or for Quantum: |
| 10 | + quantum: [cron: [enabled: true]], |
| 11 | + ] |
| 12 | +``` |
| 13 | + |
| 14 | +## Manual Setup |
| 15 | + |
| 16 | +If you're using another library or a custom solution for scheduling jobs, you'll need to instrument those jobs manually. |
| 17 | + |
| 18 | +### Check-Ins (Recommended) |
| 19 | + |
| 20 | +Check-in monitoring allows you to track a job's progress by completing **two check-ins**: one at the start of your job, and another at the end of your job. This two-step process allows Sentry to notify you if your job didn't start when expected (missed) or if it exceeded its maximum runtime (failed). |
| 21 | + |
| 22 | +```elixir |
| 23 | +{:ok, check_in_id} = Sentry.capture_check_in(status: :in_progress, monitor_slug: "<monitor-slug>") |
| 24 | + |
| 25 | +# Execute your scheduled task here |
| 26 | +my_scheduled_job() |
| 27 | + |
| 28 | +Sentry.capture_check_in(check_in_id: check_in_id, status: :ok, monitor_slug: "<monitor-slug>") |
| 29 | +``` |
| 30 | + |
| 31 | +If your job execution fails, you can notify Sentry about the failure: |
| 32 | + |
| 33 | +```elixir |
| 34 | +Sentry.capture_check_in(check_in_id: check_in_id, status: :error, monitor_slug: "<monitor-slug>") |
| 35 | +``` |
| 36 | + |
| 37 | +### Heartbeats |
| 38 | + |
| 39 | +Heartbeat monitoring notifies Sentry of a job's status through _a single check-in_. This setup will only notify you if your job didn't start when expected (missed). If you need to track a job to see if it exceeded its maximum runtime (failed), use check-ins instead. |
| 40 | + |
| 41 | +```elixir |
| 42 | +Sentry.capture_check_in(status: :ok, monitor_slug: "<monitor-slug>") |
| 43 | +``` |
| 44 | + |
| 45 | +If your job execution fails, you can notify Sentry about the failure: |
| 46 | + |
| 47 | +```elixir |
| 48 | +Sentry.capture_check_in(status: :error, monitor_slug: "<monitor-slug>") |
| 49 | +``` |
| 50 | + |
| 51 | +## Upserting Cron Monitors |
| 52 | + |
| 53 | +You can create and update your monitors programmatically with code rather than [creating and configuring them in Sentry](https://sentry.io/crons/create/). |
| 54 | + |
| 55 | +To do that, you need to pass a `:monitor_config` set of options to `Sentry.capture_check_in/3`: |
| 56 | + |
| 57 | +```elixir |
| 58 | +# Create a config from a crontab schedule (every 10 minutes) |
| 59 | +monitor_config = [ |
| 60 | + schedule: [ |
| 61 | + type: :crontab, |
| 62 | + value: "5 * * * *", |
| 63 | + ], |
| 64 | + checkin_margin: 5, # Optional check-in margin in minutes |
| 65 | + max_runtime: 15, # Optional max runtime in minutes |
| 66 | + timezone: "Europe/Vienna", # Optional timezone |
| 67 | +] |
| 68 | + |
| 69 | +# Alternatively, create a config from an interval schedule (every 10 minutes in this case): |
| 70 | +monitor_config = [ |
| 71 | + schedule: [ |
| 72 | + type: :interval, |
| 73 | + unit: :minute, |
| 74 | + value: 10 |
| 75 | + ], |
| 76 | + checkin_margin: 5, # Optional check-in margin in minutes |
| 77 | + max_runtime: 15, # Optional max runtime in minutes |
| 78 | + timezone: "Europe/Vienna", # Optional timezone |
| 79 | +] |
| 80 | + |
| 81 | +# Notify Sentry your job is running: |
| 82 | +{:ok, check_in_id} = |
| 83 | + Sentry.capture_check_in( |
| 84 | + status: :in_progress, |
| 85 | + monitor_slug: "<monitor-slug>", |
| 86 | + monitor_config: monitor_config |
| 87 | + ) |
| 88 | + |
| 89 | +# Execute your job: |
| 90 | +execute_job() |
| 91 | + |
| 92 | +# Notify Sentry your job has completed successfully: |
| 93 | +Sentry.capture_check_in( |
| 94 | + status: :ok, |
| 95 | + check_in_id: check_in_id, |
| 96 | + monitor_slug: "<monitor-slug>", |
| 97 | + monitor_config: monitor_config |
| 98 | +) |
| 99 | +``` |
0 commit comments