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.

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.

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.

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 and FireInstanceId on the rows you store. The recorder sets them.
• 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.