SDK de .NET

SteadyCron.Monitoring es el SDK oficial de monitorización por código para .NET. Envuelve un job programado con TrackAsync y SteadyCron sabrá cuándo comenzó, tuvo éxito o falló — y te alertará si no se ejecuta a tiempo o comienza pero nunca termina.

El SDK nunca crea monitores. Declaras el monitor heartbeat como código — en un manifiesto YAML o con el provider de Terraform — y lo referencias desde tu aplicación por su key estable. El horario cron, las reglas de alerta y la instrumentación viven así en el mismo repositorio.

Instalación

dotnet add package SteadyCron.Monitoring

Inicio rápido

ASP.NET Core / Generic Host

Registra el monitor mediante inyección de dependencias:

// Program.cs
builder.Services.AddSteadyCron(o =>
{
    o.ApiKey = builder.Configuration["SteadyCron:ApiKey"]; // clave de solo lectura
    o.Environment = builder.Environment.EnvironmentName;   // opcional
});

// 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 cadena "nightly-db-backup" es el mismo key que defines en el recurso steadycron_heartbeat_monitor (Terraform) o como id del job heartbeat (manifiesto YAML). Ese es el único contrato entre tu schedule-as-code y tu aplicación.

Consola / independiente (sin DI)

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

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

Autenticación

El SDK usa una clave API de solo lectura para resolver un key de monitor a su token de ping al iniciar. Crea una en Configuración → Claves API → Nueva clave → Alcance: Solo lectura.

Proporciónala mediante cualquiera de estas opciones:

• Variable de entorno: STEADYCRON_API_KEY=sc_ro_...
• Directamente mediante SteadyCronOptions.ApiKey
• "SteadyCron:ApiKey" en appsettings.json

Configuración

Propiedad	Por defecto	Variable de entorno
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 segundos	—
ResolveCacheTtl	1 hora	—

Cómo funciona

1. En el primer uso, el SDK llama a GET /api/monitors/resolve?key=<tu-key> con la clave API de solo lectura para obtener el token de ping. El token se almacena en caché durante una hora (configurable mediante ResolveCacheTtl).
2. Todos los pings son fire-and-forget: se aplica un timeout acotado (~5 s); los errores de transporte se registran y se descartan, nunca se propagan.
3. Los errores de resolución — 404 (key desconocido), 409 (key ambiguo) o tipo incorrecto — se lanzan inmediatamente. Indican un error de configuración.
4. Ante una excepción dentro de TrackAsync, se envía un ping fail y la excepción original se relanza sin modificar.

Modo directo / token

Si no puedes usar la resolución por clave API (por ejemplo, en un entorno aislado), define el token de ping directamente y omite la llamada de resolución:

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

El token está visible en el dashboard bajo Detalle del job → Monitorización por código → Revelar token de ping.

Garantía de fiabilidad

• Los fallos de ping nunca se propagan. Un error de transporte, timeout o respuesta no-2xx de un ping se registra en Warning/Debug y se descarta.
• Los errores de resolución siempre se propagan. Un 404 o 409 del endpoint de resolución lanza una excepción en el primer uso; corrige el key o elimina el decorador.
• Las excepciones originales pasan sin cambios. TrackAsync no envuelve tus excepciones — el ping fail se envía antes de relanzar.
• Ningún ping bloquea el job. Los pings se ejecutan en línea pero están acotados por PingTimeout (por defecto 5 s). Un ping lento retrasa el job pero nunca lo bloquea.

Relacionado

• Monitorización heartbeat — cómo se detectan ejecuciones perdidas, fallidas y bloqueadas
• SDK de Python — el mismo flujo de monitorización por código para Python
• Provider de Terraform — declarar el monitor y su key en HCL
• YAML y CLI — declarar el monitor en un manifiesto en su lugar
• Snippets de ping — hacer ping desde cualquier lenguaje o shell, sin el SDK