SteadyCron.Monitoring 0.1.0

SteadyCron .NET SDK

SteadyCron.Monitoring is the official .NET code-monitoring SDK for SteadyCron.

Wrap your scheduled jobs with TrackAsync and SteadyCron will:

• Know when a job started, succeeded, or failed
• Alert you when a job doesn't run on time (missed heartbeat)
• Detect stuck runs that start but never finish

The monitor must already exist — create it in the Dashboard, via YAML manifest, or Terraform. The SDK never creates monitors. For a fully code-driven workflow, declare the monitor in your Terraform configuration or YAML manifest and reference it from your application by key: the cron schedule, alert rules, and SDK instrumentation all live in the same repository.

Installation

dotnet add package SteadyCron.Monitoring

Quick start

ASP.NET Core / Generic Host

// Program.cs
builder.Services.AddSteadyCron(o =>
{
    o.ApiKey = builder.Configuration["SteadyCron:ApiKey"]; // read-only key
    o.Environment = builder.Environment.EnvironmentName;   // optional
});

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

Console / standalone (no DI)

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

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

Authentication

The SDK uses a read-only API key to resolve monitor keys to ping tokens at startup. Create one in:

SteadyCron Dashboard → Settings → API keys → New key → Scope: Read-only

Set it via:

• Environment variable: STEADYCRON_API_KEY=sc_ro_...
• SteadyCronOptions.ApiKey directly
• "SteadyCron:ApiKey" in appsettings.json

How it works

1. On first use, the SDK calls GET /api/monitors/resolve?key=<your-key> with the read-only API key to retrieve the ping token. The token is cached for 1 hour (configurable).
2. All pings are fire-and-forget: a bounded timeout (~5 s) is applied; transport errors are logged and swallowed, never propagated.
3. Resolution errors (404 unknown key, 409 ambiguous key, wrong kind) are raised immediately — they indicate misconfiguration.
4. On exception inside TrackAsync, a fail ping is sent and the original exception is rethrown unchanged.

Configuration

Direct / token mode (hardened path)

If you cannot use API key resolution (e.g. air-gapped environments), set the ping token directly:

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

The token is visible via Job detail → Code monitoring → Reveal ping token in the Dashboard.

Reliability contract

• Ping failures are never propagated. A transport error, timeout, or non-2xx response from a ping is logged at Warning/Debug and discarded.
• Resolution errors always propagate. A 404 or 409 from the resolve endpoint raises on first use; fix the key or remove the decorator.
• Original exceptions pass through unchanged. TrackAsync does not wrap exceptions. The fail ping is sent before rethrowing.
• No ping blocks the job. Pings run inline but are bounded by PingTimeout (default 5 s). A slow ping delays but never hangs the job.

License

MIT