SDK .NET

SteadyCron.Monitoring est le SDK officiel de surveillance par code pour .NET. Encapsulez une tâche planifiée avec TrackAsync et SteadyCron saura quand elle a démarré, réussi ou échoué — et vous alertera si elle ne s’exécute pas à l’heure prévue ou démarre sans jamais se terminer.

Le SDK ne crée jamais de monitors. Vous déclarez le monitor heartbeat en code — dans un manifeste YAML ou avec le provider Terraform — puis le référencez depuis votre application par son key stable. Le planning cron, les règles d’alerte et l’instrumentation vivent ainsi dans le même dépôt.

Installation

dotnet add package SteadyCron.Monitoring

Démarrage rapide

ASP.NET Core / Generic Host

Enregistrez le monitor par injection de dépendances :

// Program.cs
builder.Services.AddSteadyCron(o =>
{
    o.ApiKey = builder.Configuration["SteadyCron:ApiKey"]; // clé en lecture seule
    o.Environment = builder.Environment.EnvironmentName;   // optionnel
});

// 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);
    }
}

La chaîne "nightly-db-backup" est le même key que celui défini sur la ressource steadycron_heartbeat_monitor (Terraform) ou comme id de la tâche heartbeat (manifeste YAML). C’est le seul contrat entre votre schedule-as-code et votre application.

Console / autonome (sans DI)

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

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

Authentification

Le SDK utilise une clé API en lecture seule pour résoudre un key de monitor en jeton de ping au démarrage. Créez-en une dans Paramètres → Clés API → Nouvelle clé → Portée : Lecture seule.

Fournissez-la via l’une de ces méthodes :

• Variable d’environnement : STEADYCRON_API_KEY=sc_ro_...
• Directement via SteadyCronOptions.ApiKey
• "SteadyCron:ApiKey" dans appsettings.json

Configuration

Propriété	Défaut	Variable d’environnement
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 secondes	—
ResolveCacheTtl	1 heure	—

Fonctionnement

1. À la première utilisation, le SDK appelle GET /api/monitors/resolve?key=<votre-key> avec la clé API en lecture seule pour récupérer le jeton de ping. Le jeton est mis en cache pendant une heure (configurable via ResolveCacheTtl).
2. Tous les pings sont fire-and-forget : un timeout borné (~5 s) est appliqué ; les erreurs de transport sont journalisées puis abandonnées, jamais propagées.
3. Les erreurs de résolution — 404 (key inconnu), 409 (key ambigu) ou type incorrect — sont levées immédiatement. Elles indiquent une erreur de configuration.
4. En cas d’exception dans TrackAsync, un ping fail est envoyé et l’exception d’origine est relevée inchangée.

Mode direct / jeton

Si vous ne pouvez pas utiliser la résolution par clé API (par exemple dans un environnement isolé), définissez le jeton de ping directement et court-circuitez l’appel de résolution :

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

Le jeton est visible dans le tableau de bord sous Détail de la tâche → Surveillance par code → Révéler le jeton de ping.

Garanties de fiabilité

• Les échecs de ping ne sont jamais propagés. Une erreur de transport, un timeout ou une réponse non-2xx d’un ping est journalisée en Warning/Debug puis abandonnée.
• Les erreurs de résolution sont toujours propagées. Un 404 ou 409 du point de résolution lève une exception à la première utilisation ; corrigez le key ou retirez le décorateur.
• Les exceptions d’origine passent inchangées. TrackAsync n’enveloppe pas vos exceptions — le ping fail est envoyé avant la relève.
• Aucun ping ne bloque la tâche. Les pings s’exécutent en ligne mais sont bornés par PingTimeout (défaut 5 s). Un ping lent retarde la tâche mais ne la bloque jamais.

Voir aussi

• Surveillance heartbeat — comment les exécutions manquées, échouées et bloquées sont détectées
• SDK Python — le même workflow de surveillance par code pour Python
• Provider Terraform — déclarer le monitor et son key en HCL
• YAML & CLI — déclarer le monitor dans un manifeste à la place
• Extraits de ping — pinguer depuis n’importe quel langage ou shell, sans le SDK