Cronitor API

.NET SDK

Use the Cronitor.Sdk NuGet package to report job runs, heartbeats, and metrics to Cronitor from C# and other .NET languages.

Install

dotnet add package Cronitor.Sdk

The package id is Cronitor.Sdk. The namespace is Cronitor. The package targets netstandard2.0 and net8.0.

Configure

Set the CRONITOR_API_KEY environment variable to your SDK Integration key. Copy the key from Settings → API Keys at https://cronitor.io/app/settings/api. Keep the key in the environment or a secret store of the runtime. Do not commit it.

new CronitorOptions() reads CRONITOR_API_KEY. Do not set ApiKey in code:

using Cronitor;

var cronitor = new CronitorClient(new CronitorOptions());

Monitor a job

Wrap the main function of the job with JobAsync:

using Cronitor;

var cronitor = new CronitorClient(new CronitorOptions());

await cronitor.JobAsync("send-invoices", async () =>
{
    await SendInvoicesAsync();
});
  • Before the function starts, the SDK sends a run event.
  • When the function returns, the SDK sends a complete event with the elapsed time as the duration metric.
  • When the function throws, the SDK sends a fail event with the exception message and the duration metric. Then it throws the exception again.
  • The events go to the monitor with the key send-invoices. If no monitor has this key, Cronitor creates one on the first event.

For synchronous code, use cronitor.Job("send-invoices", () => SendInvoices()). The SDK sends the return value of the function as the message of the complete event. To not send it, give new JobOptions { LogOutput = false } as the third argument.

To send the events yourself, use a monitor:

var monitor = cronitor.Monitor("send-invoices");
await monitor.PingAsync(new PingOptions { State = PingState.Run });
await monitor.PingAsync(new PingOptions { State = PingState.Complete }); // or PingState.Fail

Send a heartbeat

Send a ping each time the process completes a unit of useful work:

var monitor = cronitor.Monitor("queue-worker");
await monitor.PingAsync(new PingOptions { Message = "Alive!" });

To attach metrics, set Metrics. The SDK sends each item as metric=name:value:

await monitor.PingAsync(new PingOptions
{
    Metrics = new Dictionary<string, double> { ["count"] = 100, ["error_count"] = 3 },
});

If you only want to record custom metrics, use a heartbeat monitor. See Custom Metrics.

Verify

After one real run, check the state of the monitor. A successful telemetry response shows only that Cronitor received the request. It does not show that Cronitor stored the event or matched it to a monitor.

With the MCP server:

get_status({"key": "send-invoices"})

With CronitorCLI:

cronitor status send-invoices

PingAsync does not throw. It returns false and logs an error when no API key is set or when the ping fails after retries. The SDK logs through an ILogger only when you give one to the client.

Reference

Previous
Rust SDK
Next
Telemetry