feat: Check-In Upserts

CHANGELOG.md

@@ -8,6 +8,7 @@
 
 ### Features
 
+- The SDK now supports monitor upserting. You can programmatically set up your monitors via the options callback in `SentrySdk.CaptureCheckIn` ([#3330](https://github.com/getsentry/sentry-dotnet/pull/3330))
 - Added an `SentrySdk.RunAsyncVoid` helper method that lets you capture exceptions from `async void` methods ([#3379](https://github.com/getsentry/sentry-dotnet/pull/3379))
 
 ### Fixes

src/Sentry/Extensibility/DiagnosticLoggerExtensions.cs

@@ -252,6 +252,15 @@ public static void LogError(
         string message)
         => logger.LogIfEnabled(SentryLevel.Error, null, message);
 
+    /// <summary>
+    /// Log an error message.
+    /// </summary>
+    public static void LogError<TArg>(
+        this IDiagnosticLogger logger,
+        string message,
+        TArg arg)
+        => logger.LogIfEnabled(SentryLevel.Error, null, message, arg);
+
     /// <summary>
     /// Log an exception with an error message.
     /// </summary>

src/Sentry/Extensibility/DisabledHub.cs

@@ -183,8 +183,13 @@ public void CaptureSession(SessionUpdate sessionUpdate)
     /// <summary>
     /// No-Op
     /// </summary>
-    public SentryId CaptureCheckIn(string monitorSlug, CheckInStatus status, SentryId? sentryId = null,
-        TimeSpan? duration = null, Scope? scope = null)
+    public SentryId CaptureCheckIn(
+        string monitorSlug,
+        CheckInStatus status,
+        SentryId? sentryId = null,
+        TimeSpan? duration = null,
+        Scope? scope = null,
+        Action<SentryMonitorOptions>? configureMonitorOptions = null)
         => SentryId.Empty;
 
     /// <summary>

src/Sentry/Extensibility/HubAdapter.cs

@@ -270,9 +270,14 @@ public void CaptureSession(SessionUpdate sessionUpdate)
     /// <summary>
     /// Forwards the call to <see cref="SentrySdk"/>.
     /// </summary>
-    public SentryId CaptureCheckIn(string monitorSlug, CheckInStatus status, SentryId? sentryId = null,
-        TimeSpan? duration = null, Scope? scope = null)
-        => SentrySdk.CaptureCheckIn(monitorSlug, status, sentryId, duration);
+    public SentryId CaptureCheckIn(
+        string monitorSlug,
+        CheckInStatus status,
+        SentryId? sentryId = null,
+        TimeSpan? duration = null,
+        Scope? scope = null,
+        Action<SentryMonitorOptions>? monitorOptions = null)
+        => SentrySdk.CaptureCheckIn(monitorSlug, status, sentryId, duration, scope, monitorOptions);
 
     /// <summary>
     /// Forwards the call to <see cref="SentrySdk"/>

src/Sentry/ISentryClient.cs

@@ -79,8 +79,13 @@ public interface ISentryClient
     /// <param name="sentryId"></param>
     /// <param name="duration"></param>
     /// <param name="scope"></param>
-    SentryId CaptureCheckIn(string monitorSlug, CheckInStatus status, SentryId? sentryId = null,
-        TimeSpan? duration = null, Scope? scope = null);
+    /// <param name="configureMonitorOptions">The optional monitor config used to create a Check-In programmatically.</param>
+    SentryId CaptureCheckIn(string monitorSlug,
+        CheckInStatus status,
+        SentryId? sentryId = null,
+        TimeSpan? duration = null,
+        Scope? scope = null,
+        Action<SentryMonitorOptions>? configureMonitorOptions = null);
 
     /// <summary>
     /// Flushes the queue of captured events until the timeout is reached.

src/Sentry/Internal/Hub.cs

@@ -561,9 +561,13 @@ public void CaptureSession(SessionUpdate sessionUpdate)
         }
     }
 
-    public SentryId CaptureCheckIn(string monitorSlug, CheckInStatus status, SentryId? sentryId = null,
+    public SentryId CaptureCheckIn(
+        string monitorSlug,
+        CheckInStatus status,
+        SentryId? sentryId = null,
         TimeSpan? duration = null,
-        Scope? scope = null)
+        Scope? scope = null,
+        Action<SentryMonitorOptions>? configureMonitorOptions = null)
     {
         if (!IsEnabled)
         {
@@ -580,7 +584,7 @@ public SentryId CaptureCheckIn(string monitorSlug, CheckInStatus status, SentryI
                 scope = currentScope;
             }
 
-            return _ownedClient.CaptureCheckIn(monitorSlug, status, sentryId, duration, scope);
+            return _ownedClient.CaptureCheckIn(monitorSlug, status, sentryId, duration, scope, configureMonitorOptions);
         }
         catch (Exception e)
         {

src/Sentry/SentryCheckIn.cs

@@ -4,7 +4,7 @@
 namespace Sentry;
 
 /// <summary>
-/// The Checkin Status
+/// The Check-In Status
 /// </summary>
 public enum CheckInStatus
 {
@@ -25,13 +25,13 @@ public enum CheckInStatus
 }
 
 /// <summary>
-/// Sentry Checkin
+/// Sentry Check-In
 /// </summary>
 // https://develop.sentry.dev/sdk/check-ins/
 public class SentryCheckIn : ISentryJsonSerializable
 {
     /// <summary>
-    /// CheckIn ID
+    /// Check-In ID
     /// </summary>
     public SentryId Id { get; }
 
@@ -40,13 +40,14 @@ public class SentryCheckIn : ISentryJsonSerializable
     /// </summary>
     public string MonitorSlug { get; }
 
+
     /// <summary>
-    /// The status of the Checkin
+    /// The status of the Check-In
     /// </summary>
     public CheckInStatus Status { get; }
 
     /// <summary>
-    /// The duration of the check-in in seconds. Will only take effect if the status is ok or error.
+    /// The duration of the Check-In in seconds. Will only take effect if the status is ok or error.
     /// </summary>
     public TimeSpan? Duration { get; set; }
 
@@ -65,6 +66,11 @@ public class SentryCheckIn : ISentryJsonSerializable
     /// </summary>
     internal SentryId? TraceId { get; set; }
 
+    /// <summary>
+    /// The Monitor Config
+    /// </summary>
+    internal SentryMonitorOptions? MonitorOptions { get; set; }
+
     /// <summary>
     /// Initializes a new instance of <see cref="SentryCheckIn"/>.
     /// </summary>
@@ -103,6 +109,8 @@ public void WriteTo(Utf8JsonWriter writer, IDiagnosticLogger? logger)
             writer.WriteEndObject();
         }
 
+        MonitorOptions?.WriteTo(writer, logger);
+
         writer.WriteEndObject();
     }
 

src/Sentry/SentryClient.cs

@@ -220,7 +220,13 @@ public void CaptureSession(SessionUpdate sessionUpdate)
         => CaptureEnvelope(Envelope.FromSession(sessionUpdate));
 
     /// <inheritdoc />
-    public SentryId CaptureCheckIn(string monitorSlug, CheckInStatus status, SentryId? sentryId = null, TimeSpan? duration = null, Scope? scope = null)
+    public SentryId CaptureCheckIn(
+        string monitorSlug,
+        CheckInStatus status,
+        SentryId? sentryId = null,
+        TimeSpan? duration = null,
+        Scope? scope = null,
+        Action<SentryMonitorOptions>? configureMonitorOptions = null)
     {
         scope ??= new Scope(_options);
 
@@ -234,9 +240,16 @@ public SentryId CaptureCheckIn(string monitorSlug, CheckInStatus status, SentryI
         var checkIn = new SentryCheckIn(monitorSlug, status, sentryId)
         {
             Duration = duration,
-            TraceId = traceId
+            TraceId = traceId,
         };
 
+        if (configureMonitorOptions is not null)
+        {
+            var monitorOptions = new SentryMonitorOptions();
+            configureMonitorOptions.Invoke(monitorOptions);
+            checkIn.MonitorOptions = monitorOptions;
+        }
+
         _enricher.Apply(checkIn);
 
         return CaptureEnvelope(Envelope.FromCheckIn(checkIn))

src/Sentry/SentryMonitorOptions.cs

@@ -0,0 +1,188 @@
+using Sentry.Extensibility;
+using Sentry.Internal.Extensions;
+
+namespace Sentry;
+
+internal enum SentryMonitorScheduleType
+{
+    None,
+    Crontab,
+    Interval
+}
+
+/// <summary>
+/// Sentry's intervals for monitors
+/// </summary>
+public enum SentryMonitorInterval
+{
+    /// <summary>
+    /// Year
+    /// </summary>
+    Year,
+
+    /// <summary>
+    /// Month
+    /// </summary>
+    Month,
+
+    /// <summary>
+    /// Week
+    /// </summary>
+    Week,
+
+    /// <summary>
+    /// Day
+    /// </summary>
+    Day,
+
+    /// <summary>
+    /// Hour
+    /// </summary>
+    Hour,
+
+    /// <summary>
+    /// Minute
+    /// </summary>
+    Minute
+}
+
+/// <summary>
+/// Sentry's options for monitors
+/// </summary>
+public class SentryMonitorOptions : ISentryJsonSerializable
+{
+    private SentryMonitorScheduleType _type = SentryMonitorScheduleType.None;
+    private string? _crontab;
+    private int? _interval;
+    private SentryMonitorInterval? _unit;
+
+    // Breakdown of the validation
+    // ^(\*|([0-5]?\d))                 Minute  0 - 59
+    // (\s+)(\*|([01]?\d|2[0-3]))       Hour    0 - 23
+    // (\s+)(\*|([1-9]|[12]\d|3[01]))   Day     1 - 31
+    // (\s+)(\*|([1-9]|1[0-2]))         Month   1 - 12
+    // (\s+)(\*|([0-7]))                Weekday 0 - 7
+    // $                                End of string
+    private readonly Regex _crontabValidation = new(
+        @"^(\*|([0-5]?\d))(\s+)(\*|([01]?\d|2[0-3]))(\s+)(\*|([1-9]|[12]\d|3[01]))(\s+)(\*|([1-9]|1[0-2]))(\s+)(\*|([0-7]))$",
+        RegexOptions.Compiled | RegexOptions.CultureInvariant);
+
+    /// <summary>
+    /// Set Interval
+    /// </summary>
+    /// <param name="cronTab"></param>
+    public void Interval(string cronTab)
+    {
+        if (_type is not SentryMonitorScheduleType.None)
+        {
+            throw new ArgumentException("You tried to set the interval twice. The Check-Ins interval is supposed to be set only once.");
+        }
+
+        if (!_crontabValidation.IsMatch(cronTab))
+        {
+            throw new ArgumentException("The provided crontab does not match the expected format of '* * * * *' " +
+                                        "translating to 'minute', 'hour', 'day of the month', 'month', and 'day of the week'.");
+        }
+
+        _type = SentryMonitorScheduleType.Crontab;
+        _crontab = cronTab;
+    }
+
+    /// <summary>
+    /// Set Interval
+    /// </summary>
+    /// <param name="interval"></param>
+    /// <param name="unit"></param>
+    public void Interval(int interval, SentryMonitorInterval unit)
+    {
+        if (_type is not SentryMonitorScheduleType.None)
+        {
+            throw new ArgumentException("You tried to set the interval twice. The Check-Ins interval is supposed to be set only once.");
+        }
+
+        _type = SentryMonitorScheduleType.Interval;
+        _interval = interval;
+        _unit = unit;
+    }
+
+    /// <summary>
+    /// The allowed margin of minutes after the expected check-in time that the monitor will not be considered missed for.
+    /// </summary>
+    public TimeSpan? CheckInMargin { get; set; }
+
+    /// <summary>
+    /// The allowed duration in minutes that the monitor may be in_progress for before being considered failed due to timeout.
+    /// </summary>
+    public TimeSpan? MaxRuntime { get; set; }
+
+    /// <summary>
+    /// The number of consecutive failed check-ins it takes before an issue is created.
+    /// </summary>
+    public int? FailureIssueThreshold { get; set; }
+
+    /// <summary>
+    /// The number of consecutive OK check-ins it takes before an issue is resolved.
+    /// </summary>
+    public int RecoveryThreshold { get; set; }
+
+    /// <summary>
+    /// A tz database string representing the timezone which the monitor's execution schedule is in (i.e. "America/Los_Angeles").
+    /// </summary>
+    public string? Timezone { get; set; }
+
+    /// <summary>
+    /// An actor identifier string. This looks like 'user:john@example.com team:a-sentry-team'. IDs can also be used but will result in a poor DX.
+    /// </summary>
+    public string? Owner { get; set; }
+
+    internal SentryMonitorOptions() { }
+
+    /// <inheritdoc />
+    public void WriteTo(Utf8JsonWriter writer, IDiagnosticLogger? logger)
+    {
+        Debug.Assert(_type != SentryMonitorScheduleType.None, "The Monitor Options do not contain a valid interval." +
+                                                              "Please update your monitor options by setting the Interval.");
+
+        writer.WriteStartObject("monitor_config");
+        writer.WriteStartObject("schedule");
+
+        writer.WriteString("type", TypeToString(_type));
+        switch (_type)
+        {
+            case SentryMonitorScheduleType.Crontab:
+                Debug.Assert(string.IsNullOrEmpty(_crontab), "The provided 'crontab' cannot be an empty string.");
+                writer.WriteStringIfNotWhiteSpace("value", _crontab);
+                break;
+            case SentryMonitorScheduleType.Interval:
+                Debug.Assert(_interval != null, "The provided 'interval' cannot be null.");
+                writer.WriteNumberIfNotNull("value", _interval);
+                Debug.Assert(_unit != null, "The provided 'unit' cannot be null.");
+                writer.WriteStringIfNotWhiteSpace("unit", _unit.ToString()!.ToLower());
+                break;
+            default:
+                logger?.LogError("Invalid MonitorScheduleType: '{0}'", _type.ToString());
+                break;
+        }
+
+        writer.WriteEndObject();
+
+        writer.WriteNumberIfNotNull("checkin_margin", CheckInMargin?.TotalMinutes);
+        writer.WriteNumberIfNotNull("max_runtime", MaxRuntime?.TotalMinutes);
+        writer.WriteNumberIfNotNull("failure_issue_threshold", FailureIssueThreshold);
+        writer.WriteNumberIfNotNull("recovery_threshold", RecoveryThreshold);
+        writer.WriteStringIfNotWhiteSpace("timezone", Timezone);
+        writer.WriteStringIfNotWhiteSpace("owner", Owner);
+
+        writer.WriteEndObject();
+    }
+
+    private static string TypeToString(SentryMonitorScheduleType type)
+    {
+        return type switch
+        {
+            SentryMonitorScheduleType.Crontab => "crontab",
+            SentryMonitorScheduleType.Interval => "interval",
+            _ => throw new ArgumentException($"Unsupported Monitor Schedule Type: '{type}'.")
+        };
+    }
+}