Interface IExecutionHistoryStore
- Namespace
- Quartz.Extensibility
- Assembly
- Quartz.dll
Where what a scheduler has run and what it has missed is kept.
public interface IExecutionHistoryStoreRemarks
A job store holds what is scheduled; this holds what happened. Nothing in Quartz keeps that on its own — a fired trigger row is gone once the firing completes — so an operator looking at a dashboard, an HTTP API or a report of the last hour is looking at this.
The shipped implementation is per-process and in-memory, bounded by
ExecutionHistoryOptions; register your own before
AddQuartzExecutionHistory() to keep history somewhere that survives a restart. Both feeds
carry the node that produced each row, which is what makes an implementation shared by a whole
cluster readable.
Two feeds, one verb each way: an execution and a misfire are both written with Add* and both
read with Query*, and the paged reads are named as the scheduler's own queries are. A store
that records nowhere — one fronting a scheduler in another process, where the history is kept — is
entitled to raise NotSupportedException from the two writers.
Beside the feeds, a store may keep a JobRunStatus per job, read with QueryJobRunStatuses(JobRunStatusQuery, CancellationToken) and GetJobRunStatus(string, JobKey, CancellationToken). Every store counts its runs over time with QueryExecutionStatistics(ExecutionStatisticsQuery, CancellationToken).
Methods
AddExecution(ExecutionHistoryEntry, CancellationToken)
Records one execution, which the history reads then return.
ValueTask AddExecution(ExecutionHistoryEntry entry, CancellationToken cancellationToken = default)Parameters
entryExecutionHistoryEntryThe execution that finished.
cancellationTokenCancellationTokenThe cancellation instruction.
Returns
AddMisfire(MisfireHistoryEntry, CancellationToken)
Records one misfire, which the misfire reads then return.
ValueTask AddMisfire(MisfireHistoryEntry entry, CancellationToken cancellationToken = default)Parameters
entryMisfireHistoryEntryThe firing that was missed.
cancellationTokenCancellationTokenThe cancellation instruction.
Returns
CountMisfires(string, DateTimeOffset, CancellationToken)
How many misfires the scheduler has recorded since since.
ValueTask<int> CountMisfires(string schedulerName, DateTimeOffset since, CancellationToken cancellationToken = default)Parameters
schedulerNamestringThe scheduler whose misfires to count.
sinceDateTimeOffsetThe instant to count from.
cancellationTokenCancellationTokenThe cancellation instruction.
Returns
Remarks
A count rather than a page, because a summary asks "how bad is it right now" and a store that
keeps history in a database can answer that with one COUNT(*) instead of loading rows it
would throw away. Only Missed rows count: a firing the overlap
policy skipped, or a listener vetoed, is recorded beside the misfires, and is not one.
GetExecution(string, string, CancellationToken)
Returns one recorded execution, its Log included, or null when the scheduler has no row by that EntryId — never recorded, or trimmed since.
ValueTask<ExecutionHistoryEntry?> GetExecution(string schedulerName, string entryId, CancellationToken cancellationToken = default)Parameters
schedulerNamestringThe scheduler the execution belongs to.
entryIdstringThe row's EntryId.
cancellationTokenCancellationTokenThe cancellation instruction.
Returns
Remarks
The read a detail page makes, and the one read that carries the captured log: the listing need not, and the persistent store's does not.
A default interface member, so a store written against an earlier 4.x keeps compiling. The default reads the scheduler's whole history through QueryExecutions(ExecutionHistoryQuery, CancellationToken) and picks the row out — correct for any store, and a full read; a store that can find one row by its key overrides it.
GetJobRunStatus(string, JobKey, CancellationToken)
Returns one job's run status, or null when the store has recorded no run of it.
ValueTask<JobRunStatus?> GetJobRunStatus(string schedulerName, JobKey jobKey, CancellationToken cancellationToken = default)Parameters
schedulerNamestringThe scheduler the job belongs to.
jobKeyJobKeyThe job.
cancellationTokenCancellationTokenThe cancellation instruction.
Returns
Remarks
A default interface member. The default asks QueryJobRunStatuses(JobRunStatusQuery, CancellationToken) for that one job, so it answers wherever that does and throws NotSupportedException where it throws.
Exceptions
- NotSupportedException
The store keeps no per-job status.
QueryExecutionStatistics(ExecutionStatisticsQuery, CancellationToken)
Counts a scheduler's runs by result and times them, in buckets of fire time.
ValueTask<ExecutionStatistics> QueryExecutionStatistics(ExecutionStatisticsQuery query, CancellationToken cancellationToken = default)Parameters
queryExecutionStatisticsQueryWhich runs to count, and the bucket size.
cancellationTokenCancellationTokenThe cancellation instruction.
Returns
Remarks
What a chart of runs over time reads: one answer for a whole window, however many rows it holds, where a page of QueryExecutions(ExecutionHistoryQuery, CancellationToken) holds a few.
A default interface member, so a store written against an earlier 4.x keeps compiling. The default reads QueryExecutions(ExecutionHistoryQuery, CancellationToken) a thousand rows at a time, newest first, and counts them here. It stops after DefaultRowLimit rows and sets Truncated, so its oldest buckets may then be short. A store that can count where it keeps the rows overrides it; the shipped ones do.
QueryExecutions(ExecutionHistoryQuery, CancellationToken)
Returns one page of the recorded executions, newest first.
ValueTask<PagedResult<ExecutionHistoryEntry>> QueryExecutions(ExecutionHistoryQuery query, CancellationToken cancellationToken = default)Parameters
queryExecutionHistoryQueryWhich executions to return, and how many.
cancellationTokenCancellationTokenThe cancellation instruction.
Returns
QueryJobRunStatuses(JobRunStatusQuery, CancellationToken)
Returns one page of the per-job run statuses the store keeps, ordered by job group and then name.
ValueTask<PagedResult<JobRunStatus>> QueryJobRunStatuses(JobRunStatusQuery query, CancellationToken cancellationToken = default)Parameters
queryJobRunStatusQueryWhich statuses to return, and how many.
cancellationTokenCancellationTokenThe cancellation instruction.
Returns
Remarks
A status is folded from every execution the store records, as it records it, so it outlives the rows. The shipped in-memory store keeps one per job, up to MaxEntriesPerScheduler per scheduler.
A default interface member, so a store written against an earlier 4.x keeps compiling. The default throws NotSupportedException: the rows it could read are trimmed, so counts built from them would be wrong.
Exceptions
- NotSupportedException
The store keeps no per-job status.
QueryMisfires(MisfireHistoryQuery, CancellationToken)
Returns one page of the recorded misfires, newest first.
ValueTask<PagedResult<MisfireHistoryEntry>> QueryMisfires(MisfireHistoryQuery query, CancellationToken cancellationToken = default)Parameters
queryMisfireHistoryQueryWhich misfires to return, and how many.
cancellationTokenCancellationTokenThe cancellation instruction.