@danieljvdm/dev-kit 1.0.1 → 2.0.0

package/skills/sentry/references/sdks/dotnet/crons.md

@@ -0,0 +1,465 @@
+# Crons — Sentry .NET SDK
+
+> Minimum SDK: `Sentry` ≥ 4.2.0
+
+---
+
+## Overview
+
+Sentry Cron Monitoring detects:
+
+- **Missed check-ins** — job didn’t run at the expected time
+- **Runtime failures** — job ran but encountered an error
+- **Timeouts** — job exceeded `MaxRuntime` without completing
+
+---
+
+## `CaptureCheckIn()` API
+
+```csharp
+// Signature
+SentryId CaptureCheckIn(
+    string monitorSlug,
+    CheckInStatus status,
+    SentryId? sentryId = null,
+    TimeSpan? duration = null,
+    Scope? scope = null,
+    Action<SentryMonitorOptions>? configureMonitorOptions = null
+)
+```
+
+### Check-In Status Values
+
+| Status                     | When to use                       |
+| -------------------------- | --------------------------------- |
+| `CheckInStatus.InProgress` | Job has started, work is underway |
+| `CheckInStatus.Ok`         | Job completed successfully        |
+| `CheckInStatus.Error`      | Job failed — an error occurred    |
+
+---
+
+## Pattern A: Two-Signal Check-Ins (Recommended)
+
+Sends two signals: `InProgress` at start and `Ok`/`Error` at end.\
+Enables detection of both **missed jobs** and **timeout violations**.
+
+```csharp
+// Mark job as started — save the checkInId for correlation
+var checkInId = SentrySdk.CaptureCheckIn("my-monitor-slug", CheckInStatus.InProgress);
+
+try
+{
+    DoWork();
+
+    // Mark as successful
+    SentrySdk.CaptureCheckIn("my-monitor-slug", CheckInStatus.Ok, checkInId);
+}
+catch (Exception ex)
+{
+    // Mark as failed
+    SentrySdk.CaptureCheckIn("my-monitor-slug", CheckInStatus.Error, checkInId);
+    throw;
+}
+```
+
+---
+
+## Pattern B: Heartbeat Check-In (Simpler)
+
+Sends a single check-in **after** execution.
+Detects **missed jobs** only — cannot detect timeouts.
+
+```csharp
+try
+{
+    DoWork();
+    SentrySdk.CaptureCheckIn("my-monitor-slug", CheckInStatus.Ok);
+}
+catch
+{
+    SentrySdk.CaptureCheckIn("my-monitor-slug", CheckInStatus.Error);
+    throw;
+}
+```
+
+Optionally report the actual runtime duration:
+
+```csharp
+var sw = Stopwatch.StartNew();
+DoWork();
+sw.Stop();
+
+SentrySdk.CaptureCheckIn(
+    "my-monitor-slug",
+    CheckInStatus.Ok,
+    duration: sw.Elapsed
+);
+```
+
+---
+
+## Programmatic Monitor Configuration (Upsert)
+
+Create or update a monitor directly from code via `configureMonitorOptions`. This is
+sent with the **first** check-in and is idempotent — safe to call on every run.
+
+### Crontab Schedule
+
+```csharp
+var checkInId = SentrySdk.CaptureCheckIn(
+    "my-scheduled-job",
+    CheckInStatus.InProgress,
+    configureMonitorOptions: options =>
+    {
+        options.Interval("0 2 * * *");            // 2 AM daily (crontab expression)
+        options.CheckInMargin = TimeSpan.FromMinutes(5); // 5 min grace period before "missed"
+        options.MaxRuntime = TimeSpan.FromMinutes(30);   // alert if running longer than 30 min
+        options.TimeZone = "America/New_York";           // IANA timezone
+        options.FailureIssueThreshold = 2;               // create issue after 2 consecutive failures
+        options.RecoveryThreshold = 1;                   // resolve issue after 1 consecutive success
+    }
+);
+```
+
+### Interval-Based Schedule
+
+```csharp
+var checkInId = SentrySdk.CaptureCheckIn(
+    "my-interval-job",
+    CheckInStatus.InProgress,
+    configureMonitorOptions: options =>
+    {
+        options.Interval(6, SentryMonitorInterval.Hour); // every 6 hours
+        options.CheckInMargin = TimeSpan.FromMinutes(30);
+        options.MaxRuntime = TimeSpan.FromMinutes(120);
+        options.TimeZone = "UTC";
+        options.FailureIssueThreshold = 1;
+        options.RecoveryThreshold = 3;
+    }
+);
+```
+
+### `SentryMonitorInterval` Values
+
+| Value                          | Description         |
+| ------------------------------ | ------------------- |
+| `SentryMonitorInterval.Minute` | Per-minute interval |
+| `SentryMonitorInterval.Hour`   | Per-hour interval   |
+| `SentryMonitorInterval.Day`    | Per-day interval    |
+| `SentryMonitorInterval.Week`   | Per-week interval   |
+| `SentryMonitorInterval.Month`  | Per-month interval  |
+| `SentryMonitorInterval.Year`   | Per-year interval   |
+
+---
+
+## Monitor Configuration Reference
+
+| Option                     | Type       | Description                                             |
+| -------------------------- | ---------- | ------------------------------------------------------- |
+| `Interval(crontab)`        | method     | Standard crontab expression (e.g., `"*/15 * * * *"`)    |
+| `Interval(interval, unit)` | method     | alternative interval-based schedule                     |
+| `CheckInMargin`            | `TimeSpan` | Grace period before a missing check-in is flagged       |
+| `MaxRuntime`               | `TimeSpan` | Maximum allowed runtime before a timeout alert          |
+| `TimeZone`                 | `string`   | IANA timezone name (e.g., `"UTC"`, `"America/Chicago"`) |
+| `FailureIssueThreshold`    | `int`      | Consecutive failures before a Sentry issue is opened    |
+| `RecoveryThreshold`        | `int`      | Consecutive successes before a Sentry issue is closed   |
+
+---
+
+## ASP.NET Core — BackgroundService / IHostedService
+
+The most common .NET pattern for scheduled jobs is a `BackgroundService`. Pair it with
+`CaptureCheckIn` for full monitoring:
+
+```csharp
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using Sentry;
+
+public class NightlyReportJob : BackgroundService
+{
+    private readonly ILogger<NightlyReportJob> _logger;
+    private const string MonitorSlug = "nightly-report";
+
+    public NightlyReportJob(ILogger<NightlyReportJob> logger)
+        => _logger = logger;
+
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        while (!stoppingToken.IsCancellationRequested)
+        {
+            // Wait until next scheduled time (e.g., 2 AM)
+            await WaitUntilNextRunAsync(stoppingToken);
+
+            var checkInId = SentrySdk.CaptureCheckIn(
+                MonitorSlug,
+                CheckInStatus.InProgress,
+                configureMonitorOptions: o =>
+                {
+                    o.Interval("0 2 * * *"); // 2 AM daily
+                    o.CheckInMargin = TimeSpan.FromMinutes(15);
+                    o.MaxRuntime = TimeSpan.FromMinutes(60);
+                    o.TimeZone = "UTC";
+                    o.FailureIssueThreshold = 1;
+                    o.RecoveryThreshold = 1;
+                }
+            );
+
+            try
+            {
+                _logger.LogInformation("Starting nightly report generation");
+                await GenerateReportAsync(stoppingToken);
+                _logger.LogInformation("Nightly report completed successfully");
+
+                SentrySdk.CaptureCheckIn(MonitorSlug, CheckInStatus.Ok, checkInId);
+            }
+            catch (Exception ex)
+            {
+                _logger.LogError(ex, "Nightly report failed");
+                SentrySdk.CaptureCheckIn(MonitorSlug, CheckInStatus.Error, checkInId);
+            }
+        }
+    }
+
+    private async Task WaitUntilNextRunAsync(CancellationToken ct)
+    {
+        var now = DateTime.UtcNow;
+        var nextRun = now.Date.AddDays(now.Hour >= 2 ? 1 : 0).AddHours(2);
+        var delay = nextRun - now;
+        if (delay > TimeSpan.Zero)
+            await Task.Delay(delay, ct);
+    }
+
+    private Task GenerateReportAsync(CancellationToken ct) => Task.CompletedTask; // replace with real logic
+}
+```
+
+Register the hosted service in `Program.cs`:
+
+```csharp
+builder.Services.AddHostedService<NightlyReportJob>();
+```
+
+### Minimal IHostedService Implementation
+
+For simpler one-shot or timer-based jobs:
+
+```csharp
+public class SyncJob : IHostedService, IDisposable
+{
+    private Timer? _timer;
+    private const string MonitorSlug = "data-sync";
+
+    public Task StartAsync(CancellationToken cancellationToken)
+    {
+        _timer = new Timer(RunJob, null, TimeSpan.Zero, TimeSpan.FromHours(1));
+        return Task.CompletedTask;
+    }
+
+    private void RunJob(object? state)
+    {
+        var checkInId = SentrySdk.CaptureCheckIn(
+            MonitorSlug,
+            CheckInStatus.InProgress,
+            configureMonitorOptions: o =>
+            {
+                o.Interval(1, SentryMonitorInterval.Hour);
+                o.CheckInMargin = TimeSpan.FromMinutes(5);
+                o.MaxRuntime = TimeSpan.FromMinutes(30);
+                o.TimeZone = "UTC";
+            }
+        );
+
+        try
+        {
+            SyncData();
+            SentrySdk.CaptureCheckIn(MonitorSlug, CheckInStatus.Ok, checkInId);
+        }
+        catch
+        {
+            SentrySdk.CaptureCheckIn(MonitorSlug, CheckInStatus.Error, checkInId);
+            throw;
+        }
+    }
+
+    private void SyncData() { /* real logic here */ }
+
+    public Task StopAsync(CancellationToken cancellationToken)
+    {
+        _timer?.Change(Timeout.Infinite, 0);
+        return Task.CompletedTask;
+    }
+
+    public void Dispose() => _timer?.Dispose();
+}
+```
+
+---
+
+## Hangfire Integration
+
+A dedicated `Sentry.Hangfire` package wraps check-ins automatically around Hangfire job
+execution:
+
+```shell
+dotnet add package Sentry.Hangfire
+```
+
+Register the integration when configuring Hangfire:
+
+```csharp
+// Program.cs
+builder.Services.AddHangfire(config =>
+{
+    config.UseSqlServerStorage(connectionString);
+    config.UseSentry(); // ← enables automatic check-in wrapping
+});
+builder.Services.AddHangfireServer();
+```
+
+With Hangfire, check-ins are sent automatically for jobs annotated with the
+`[SentryMonitorSlug("...")]` attribute — no manual `CaptureCheckIn` calls needed:
+
+```csharp
+public class MyJob
+{
+    [SentryMonitorSlug("my-hangfire-job")]
+    public void Execute() { /* ... */ }
+}
+```
+
+See the
+[Hangfire integration guide](https://docs.sentry.io/platforms/dotnet/crons/hangfire/)
+for full details.
+
+---
+
+## Quartz.NET Integration
+
+**No official Quartz.NET package exists.** Use `CaptureCheckIn` manually inside
+`IJob.Execute()`:
+
+```csharp
+using Quartz;
+using Sentry;
+
+[DisallowConcurrentExecution]
+public class MyQuartzJob : IJob
+{
+    public async Task Execute(IJobExecutionContext context)
+    {
+        var slug = $"quartz-{context.JobDetail.Key.Name}";
+
+        var checkInId = SentrySdk.CaptureCheckIn(slug, CheckInStatus.InProgress,
+            configureMonitorOptions: o =>
+            {
+                o.Interval("0 */6 * * *"); // every 6 hours
+                o.CheckInMargin = TimeSpan.FromMinutes(10);
+                o.MaxRuntime = TimeSpan.FromMinutes(60);
+                o.TimeZone = "UTC";
+            }
+        );
+
+        try
+        {
+            await DoWorkAsync(context.CancellationToken);
+            SentrySdk.CaptureCheckIn(slug, CheckInStatus.Ok, checkInId);
+        }
+        catch (Exception ex)
+        {
+            SentrySdk.CaptureCheckIn(slug, CheckInStatus.Error, checkInId);
+            throw new JobExecutionException(ex);
+        }
+    }
+}
+```
+
+---
+
+## Long-Running Job Pattern (Heartbeat Loop)
+
+For processes that run continuously and should check in periodically:
+
+```csharp
+public class LongRunningProcessor : BackgroundService
+{
+    private const string MonitorSlug = "queue-processor";
+
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        while (!stoppingToken.IsCancellationRequested)
+        {
+            var checkInId = SentrySdk.CaptureCheckIn(
+                MonitorSlug,
+                CheckInStatus.InProgress,
+                configureMonitorOptions: o =>
+                {
+                    o.Interval(5, SentryMonitorInterval.Minute);
+                    o.CheckInMargin = TimeSpan.FromMinutes(2);
+                    o.MaxRuntime = TimeSpan.FromMinutes(10);
+                    o.TimeZone = "UTC";
+                }
+            );
+
+            try
+            {
+                await ProcessBatchAsync(stoppingToken);
+                SentrySdk.CaptureCheckIn(MonitorSlug, CheckInStatus.Ok, checkInId);
+            }
+            catch (Exception ex) when (!stoppingToken.IsCancellationRequested)
+            {
+                SentrySdk.CaptureCheckIn(MonitorSlug, CheckInStatus.Error, checkInId);
+                // optionally capture the exception too
+                SentrySdk.CaptureException(ex);
+            }
+
+            await Task.Delay(TimeSpan.FromMinutes(5), stoppingToken);
+        }
+    }
+}
+```
+
+---
+
+## Alerting
+
+Create issue alerts in Sentry:\
+**Alerts → Create Alert → Issues → filter** by tag `monitor.slug equals my-monitor-slug`
+
+---
+
+## Rate Limits
+
+Cron check-ins are rate-limited to **6 check-ins per minute per monitor per
+environment**. Each environment (`production`, `staging`, etc.)
+tracks independently.
+Exceeding this limit silently drops events — visible in Usage Stats.
+
+---
+
+## SDK Version Matrix
+
+| Feature                                                 | Min SDK Version    |
+| ------------------------------------------------------- | ------------------ |
+| `SentrySdk.CaptureCheckIn()`                            | **4.2.0**          |
+| Heartbeat pattern                                       | **4.2.0**          |
+| Programmatic monitor upsert (`configureMonitorOptions`) | **4.7.0**          |
+| Crontab schedule (`Interval(crontab)`)                  | **4.7.0**          |
+| Interval schedule (`SentryMonitorInterval`)             | **4.7.0**          |
+| `Sentry.Hangfire` auto-integration                      | **4.x**            |
+| Quartz.NET                                              | ❌ Manual API only |
+
+---
+
+## Troubleshooting
+
+| Issue                                       | Solution                                                                                                                                  |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| Check-ins not appearing in Sentry           | Verify `monitorSlug` matches the slug configured in Sentry; check DSN is correct and SDK is initialized                                   |
+| Monitor shows “missed” despite job running  | Increase `CheckInMargin` to allow more grace time; check server clock sync (NTP)                                                          |
+| Monitor shows “timeout”                     | Increase `MaxRuntime`; investigate why the job exceeds the expected duration                                                              |
+| Monitor not auto-created                    | Pass `configureMonitorOptions` on the **first** `CaptureCheckIn` call — the upsert creates the monitor                                    |
+| `CheckInStatus.Error` but no Sentry issue   | Configure `FailureIssueThreshold = 1` on the monitor options to create issues on first failure                                            |
+| Hangfire jobs not sending check-ins         | Ensure `config.UseSentry()` is called inside `AddHangfire`; verify Sentry SDK is initialized before Hangfire starts                       |
+| Quartz jobs not monitored                   | No official integration — add `CaptureCheckIn` manually inside `IJob.Execute()`                                                           |
+| Duplicate check-ins from multiple instances | Use a distributed lock (e.g., `IDistributedLock`) around the check-in calls, or configure Quartz/Hangfire with single-instance scheduling |