.NET-SDK

SteadyCron.Monitoring ist das offizielle .NET-Code-Monitoring-SDK. Umschließen Sie einen geplanten Job mit TrackAsync, und SteadyCron erkennt, wann er gestartet, erfolgreich war oder fehlgeschlagen ist — und alarmiert Sie, wenn er nicht planmäßig läuft oder startet, aber nie fertig wird.

Das SDK erstellt niemals Monitore. Sie deklarieren den Heartbeat-Monitor als Code — in einem YAML-Manifest oder mit dem Terraform-Provider — und referenzieren ihn aus Ihrer Anwendung über seinen stabilen key. Der Cron-Zeitplan, die Alert-Regeln und die Instrumentierung leben damit im selben Repository.

Installation

dotnet add package SteadyCron.Monitoring

Schnellstart

ASP.NET Core / Generic Host

Registrieren Sie den Monitor per Dependency Injection:

// Program.cs
builder.Services.AddSteadyCron(o =>
{
    o.ApiKey = builder.Configuration["SteadyCron:ApiKey"]; // Nur-Lesen-Schlüssel
    o.Environment = builder.Environment.EnvironmentName;   // optional
});

// BackupWorker.cs
public class BackupWorker(ISteadyCronMonitor monitor) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        await monitor.TrackAsync("nightly-db-backup", async ct =>
        {
            await RunBackupAsync(ct);
        }, ct);
    }
}

Die Zeichenkette "nightly-db-backup" ist derselbe key, den Sie auf der steadycron_heartbeat_monitor-Ressource (Terraform) oder als Heartbeat-Job-id (YAML-Manifest) gesetzt haben. Das ist der einzige Vertrag zwischen Ihrem Schedule-as-Code und Ihrer Anwendung.

Konsole / eigenständig (ohne DI)

var monitor = SteadyCronMonitor.Create(new SteadyCronOptions
{
    ApiKey = Environment.GetEnvironmentVariable("STEADYCRON_API_KEY"),
});

await monitor.TrackAsync("nightly-db-backup", ct => RunBackupAsync(ct));

Authentifizierung

Das SDK verwendet einen Nur-Lesen-API-Schlüssel, um einen Monitor-Key beim Start zu seinem Ping-Token aufzulösen. Erstellen Sie einen unter Einstellungen → API-Schlüssel → Neuer Schlüssel → Scope: Nur-Lesen.

Stellen Sie ihn auf einem dieser Wege bereit:

• Umgebungsvariable: STEADYCRON_API_KEY=sc_ro_...
• Direkt über SteadyCronOptions.ApiKey
• "SteadyCron:ApiKey" in appsettings.json

Konfiguration

Eigenschaft	Standard	Fallback-Umgebungsvariable
ApiKey	null	STEADYCRON_API_KEY
ApiUrl	https://api.steadycron.com	STEADYCRON_API_URL
PingUrl	https://ping.steadycron.com	STEADYCRON_PING_URL
Environment	null	STEADYCRON_ENVIRONMENT
CaptureErrors	false	—
PingTimeout	5 Sekunden	—
ResolveCacheTtl	1 Stunde	—

Funktionsweise

1. Bei der ersten Verwendung ruft das SDK GET /api/monitors/resolve?key=<ihr-key> mit dem Nur-Lesen-API-Schlüssel auf, um das Ping-Token abzurufen. Das Token wird eine Stunde lang zwischengespeichert (konfigurierbar über ResolveCacheTtl).
2. Alle Pings sind Fire-and-Forget: Ein begrenztes Timeout (~5 s) wird angewendet; Transportfehler werden protokolliert und verworfen, niemals weitergegeben.
3. Auflösungsfehler — 404 (unbekannter Key), 409 (mehrdeutiger Key) oder falsche Art — werden sofort ausgelöst. Sie deuten auf eine Fehlkonfiguration hin.
4. Bei einer Exception innerhalb von TrackAsync wird ein fail-Ping gesendet, und die ursprüngliche Exception wird unverändert erneut ausgelöst.

Direkt-/Token-Modus

Wenn Sie die API-Key-Auflösung nicht nutzen können (z. B. in einer abgeschotteten Umgebung), setzen Sie das Ping-Token direkt und überspringen den Resolve-Aufruf:

o.Monitors["nightly-db-backup"] = "hRkmWz8oZtlMFzvTAUdnRE";

Das Token finden Sie im Dashboard unter Job-Detail → Code-Monitoring → Ping-Token anzeigen.

Zuverlässigkeitsgarantie

• Ping-Fehler werden nie weitergegeben. Ein Transportfehler, Timeout oder eine Nicht-2xx-Antwort eines Pings wird auf Warning-/Debug-Ebene protokolliert und verworfen.
• Auflösungsfehler werden immer weitergegeben. Ein 404 oder 409 vom Resolve-Endpunkt löst beim ersten Aufruf eine Exception aus; korrigieren Sie den Key oder entfernen Sie den Decorator.
• Ursprüngliche Exceptions bleiben unverändert. TrackAsync umhüllt Exceptions nicht — der fail-Ping wird vor dem erneuten Auslösen gesendet.
• Kein Ping blockiert den Job. Pings laufen inline, sind aber durch PingTimeout begrenzt (Standard 5 s). Ein langsamer Ping verzögert den Job, hängt ihn aber nie auf.

Weiterführend

• Heartbeat-Monitoring — wie verpasste, fehlgeschlagene und hängende Läufe erkannt werden
• Python-SDK — derselbe Code-Monitoring-Workflow für Python
• Terraform-Provider — den Monitor und seinen key als HCL deklarieren
• YAML & CLI — den Monitor stattdessen in einem Manifest deklarieren
• Ping-Snippets — aus jeder Sprache oder Shell pingen, ohne das SDK