Job Outcomes

A job can say what its run achieved: a result, a one-line summary and named metrics. The execution history records them, and keeps a status per job that outlives its rows.

Report a result

Set IJobExecutionContext.Result to a JobRunReport:

public sealed class ReleaseStaleReservationsJob : IJob
{
    public async ValueTask Execute(IJobExecutionContext context, CancellationToken cancellationToken = default)
    {
        int scanned = await CountReservations(cancellationToken);
        int released = await ReleaseStale(cancellationToken);

        // A run that found nothing to do is a success, recorded as Skipped.
        context.Result = released == 0
            ? JobRunReport.Skipped("no stale reservations").With("scanned", scanned)
            : JobRunReport.Succeeded($"released {released}").With("scanned", scanned).With("released", released);
    }

    private static ValueTask<int> CountReservations(CancellationToken cancellationToken) => new(1200);

    private static ValueTask<int> ReleaseStale(CancellationToken cancellationToken) => new(0);
}

The history stores the integer. New members are appended; none is renumbered.

Which result is recorded

The first rule that holds wins:

1. The firing was cancelled: Cancelled.
2. The job threw: Failed.
3. context.Result is an IJobRunReport: its Result.
4. Otherwise: Succeeded.

• The summary and metrics are recorded whichever rule wins.
• Any other context.Result is ignored. NativeJob keeps an exit code there.
• ExecutionHistoryEntry.Succeeded is true for Succeeded and Skipped.
• The quartz.job.execution.duration histogram and the Quartz.Job.Execute span carry the same result, lower-cased, as quartz.job.result, with or without the history. See Metrics and Failed spans.

Throw to make the scheduler act

A reported Failed is history only. To have the scheduler act on a failure, throw.

Limits

Metrics are written by value type, without reflection:

• Every character outside ASCII is escaped, so 4,000 characters is also 4,000 bytes.
• With(name, value) returns a copy. A name already present takes the new value.

What else the history records

TriggerJob marks its trigger with SchedulerConstants.ManualTrigger (QRTZ_MANUAL_TRIGGER = "true") in the trigger's JobDataMap. The key persists in every store and shows in MergedJobDataMap.

Keep history by result

builder.Services.AddQuartzExecutionHistory(options =>
{
    options.Retention = TimeSpan.FromDays(1);
    options.RetentionByResult[JobRunResult.Failed] = TimeSpan.FromDays(30);
    options.RetentionByResult[JobRunResult.Skipped] = TimeSpan.FromHours(1);
    options.MisfireRetention = TimeSpan.FromDays(7);

    // A job that runs every second keeps its latest 100 runs, and every failure.
    options.MaxEntriesPerJob = 100;
    options.MaxEntriesPerScheduler = 20_000;
});

• Every age must be positive and MaxEntriesPerJob must not be negative, or the host fails at startup.
• TimeSpan.MaxValue keeps a result for good, within MaxEntriesPerScheduler.
• Both histories apply all five. The database history applies them by a sweep; its reads apply only the longest age.

Record a run's input

From 4.4, the history can keep each run's input, so a failure can be run again with it:

builder.Services.AddQuartzExecutionHistory(options =>
{
    // Off by default: an input can hold secrets, and the history keeps it as plain text.
    options.RecordInput = true;
    options.MaxInputBytes = 64 * 1024;
});

• The input is what ScheduleJob<TJob, TInput> and UsingInput store. The rest of the job data map is not kept.
• The trigger's input wins over the job's, as it did for the run.
• The history keeps it as plain text. It is never logged.
• GetExecution carries Input. A listing may leave it out; the database history and the HTTP API do.
• The database history needs the 4.4 migration's JOB_INPUT and JOB_INPUT_TOO_LARGE. See The input columns.

Run a failure again with its input, as the dashboard's Run again does:

ExecutionHistoryEntry? failed = await history.GetExecution(scheduler.SchedulerName, entryId);
if (failed is null)
{
    return;
}

// The input is the string the scheduler stored, so it goes back as it is. No input: the job's own data.
JobDataMap? data = failed.Input is { } input ? new JobDataMap { [SchedulerConstants.JobInput] = input } : null;
await scheduler.TriggerJob(new JobKey(failed.JobName, failed.JobGroup), data);

The job must still be stored. A job without StoreDurably() is deleted with its last trigger, so running a spent one-off again throws JobPersistenceException: The job (…) referenced by the trigger does not exist. Store a job you expect to run again with StoreDurably(); ScheduleJob<TJob, TInput> already stores its job durably.

Read a job's status

JobRunStatus? status = await history.GetJobRunStatus(schedulerName, new JobKey("release-stale", "billing"));
if (status is { ConsecutiveFailures: > 0 })
{
    Console.WriteLine($"failing {status.ConsecutiveFailures}x since {status.LastSucceededAtUtc}: {status.LastFailureMessage}");
}

PagedResult<JobRunStatus> failing = await history.QueryJobRunStatuses(
    new JobRunStatusQuery { SchedulerName = schedulerName, Failing = true });

• A status is folded from each row as it is recorded, so it outlives trimming.
• A run that completes after a later-fired run is counted. It does not change the Last* run fields or ConsecutiveFailures.
• JobRunStatusQuery pages by job group, then name. Failing = true lists ConsecutiveFailures > 0; Jobs names the jobs.

Filter the history

PagedResult<ExecutionHistoryEntry> page = await history.QueryExecutions(new ExecutionHistoryQuery
{
    SchedulerName = schedulerName,
    Job = new JobKey("release-stale", "billing"),
    FiredFrom = since,
    Results = [JobRunResult.Failed, JobRunResult.Cancelled]
});

foreach (ExecutionHistoryEntry row in page.Items)
{
    // EffectiveResult answers for rows written before 4.4, which carry no Result.
    Console.WriteLine($"{row.FiredAtUtc:O} {row.EffectiveResult} {row.Summary} {row.MetricsJson}");
}

• MisfireHistoryQuery.Job narrows the misfire feed the same way, and MisfireHistoryQuery.Reasons to some MisfireReasons. An empty set matches nothing. A row a 4.2 node wrote has no reason and matches Missed.
• A cancelled run matches FailedFinally = true.

Count runs over time

From 4.4. One call counts every run a window holds, per bucket of fire time:

ExecutionStatistics statistics = await history.QueryExecutionStatistics(new ExecutionStatisticsQuery
{
    SchedulerName = schedulerName,
    Job = new JobKey("release-stale", "billing"),
    FiredFrom = since,
    BucketSize = TimeSpan.FromHours(1)
});

foreach (ExecutionStatisticsBucket bucket in statistics.Buckets)
{
    // One bucket per hour that holds a run, oldest first.
    Console.WriteLine($"{bucket.StartUtc:O} {bucket.RunCount} runs, {bucket.FailedCount} failed, p95 {bucket.P95Duration}");
}

• A bucket with no run is left out. Buckets is oldest first.
• A percentile interpolates between the two runs either side of rank (n - 1) * p, as SQL's PERCENTILE_CONT does. Every store gives the same answer.
• The age bound applies, as it does to a listing.

Measured on 1,000,000 rows over 30 days:

See it in the dashboard and over HTTP

GET /quartz-api/schedulers/QuartzScheduler/history/executions?jobGroup=billing&jobName=release-stale&results=Failed,Cancelled
GET /quartz-api/schedulers/QuartzScheduler/history/job-status?failing=true

• A vetoed firing is listed only when reasons names Vetoed, so a 4.3 client can read the default listing. The dashboard and AddQuartzHttpClient ask for it.
• A scheduler in another process whose host is older than 4.4 has no statuses and cannot filter. The dashboard leaves the columns out and says so on the History page.

Alert when a job stops succeeding

The Quartz health check reports a job that has not succeeded within a window:

builder.Services.AddQuartzExecutionHistory();
builder.Services.AddHealthChecks().AddQuartz(options =>
{
    // Degraded once the nightly report has not succeeded for 26 hours.
    options.RequireSuccessWithin(new JobKey("nightly-report", "reports"), TimeSpan.FromHours(26));

    // Unhealthy, so the node leaves the rotation, once the ledger has not closed for 90 minutes.
    options.RequireSuccessWithin(new JobKey("ledger-close", "billing"), TimeSpan.FromMinutes(90), HealthStatus.Unhealthy);
});

• The window runs from JobRunStatus.LastSucceededAtUtc, on the scheduler's clock. A Skipped run is a success.
• A job with no recorded success is judged from the first time the check evaluated it. A process that has just started gives each job one window.
• The check reports the worst of the scheduler's own verdict and each late job's Status. It does not read the jobs of a scheduler that is already unhealthy. It does read them in standby.
• The message names the gravest late job and counts the others. The data has one entry per late job, keyed <group>.<name>: lastSucceededAtUtc (or never), consecutiveFailures and succeededWithin.
• Every check reads all the jobs' statuses in one call.
• A job given twice keeps the later entry. RequireSuccessWithin replaces the earlier one.

The statuses come from the execution history, which must keep them: see the table under Read a job's status.

RequiredJobs binds from configuration. A TimeSpan is d.hh:mm:ss, so 26 hours is 1.02:00:00:

{
  "HealthChecks": {
    "Quartz": {
      "RequiredJobs": [
        { "Name": "nightly-report", "Group": "reports", "SucceededWithin": "1.02:00:00" },
        { "Name": "ledger-close", "Group": "billing", "SucceededWithin": "01:30:00", "Status": "Unhealthy" }
      ]
    }
  }
}

Bind it with services.Configure<QuartzHealthCheckOptions>(configuration.GetSection("HealthChecks:Quartz")), or under the scheduler's name for a named scheduler.

A history store of your own

• Keep Result, Summary, MetricsJson, Manual, FireInstanceId, Input and InputTooLarge on the rows you store. The recorder sets them. Return Input from GetExecution; a listing may leave it out.
• Apply the four filters above, MisfireHistoryQuery.Job and MisfireHistoryQuery.Reasons.
• Count only MisfireReason.Missed rows in CountMisfires.
• QueryJobRunStatuses and GetJobRunStatus are default interface members. The first throws NotSupportedException; the second asks the first for one job. Implement QueryJobRunStatuses to keep a status beside the rows, updated as each row is recorded.
• QueryExecutionStatistics is a default interface member that counts through QueryExecutions, up to 10,000 rows. Implement it to count where the rows are kept. See Count runs over time.