Immediate.Jobs.Dashboard

Immediate.Jobs.Dashboard

An embedded monitoring dashboard and stable HTTP API for Immediate.Jobs. The package serves an embedded SPA plus Immediate.Apis-generated JSON and Server-Sent Events endpoints.

Installation

dotnet add package Immediate.Jobs --prerelease
dotnet add package Immediate.Jobs.Dashboard --prerelease

Registration and mapping

Add the dashboard to the generated jobs builder before building the app, then map it:

using Immediate.Jobs.Dashboard;

builder.Services.AddMyAppHandlers();
builder.Services.AddMyAppJobs()
	.ConfigureStorage(storage => storage.UseInMemory())
	.AddImmediateJobsDashboard()
	.ConfigureDashboard(options => options.AuthorizationPolicy = "operations");

var app = builder.Build();
app.MapImmediateJobsDashboard("/jobs");

Dashboard options use the .NET options system and are validated when the host starts. Configure them through ConfigureDashboard; MapImmediateJobsDashboard only selects the URL path.

Without an authorization policy, every dashboard endpoint is allowed only in the Development environment and returns 403 elsewhere. For a trusted custom development environment, explicitly disable this restriction during registration:

builder.Services.AddMyAppJobs()
	.ConfigureStorage(storage => storage.UseInMemory())
	.AddImmediateJobsDashboard()
	.ConfigureDashboard(options => options.RestrictToDevelopmentEnvironment = false);

var app = builder.Build();
app.MapImmediateJobsDashboard("/jobs");

Treat the dashboard as an administrative surface: it exposes payloads, errors, identifiers, and mutations. Prefer setting AuthorizationPolicy whenever the dashboard is exposed outside a trusted environment. A named policy applies to UI assets and APIs together and replaces the development-only restriction.

Immediate.Validations returns application/problem+json for invalid route and paging inputs.

Features

The dashboard includes:

• filtered, server-paged job search;
• job details and retained execution attempts;
• recurring schedule actions;
• definition pause/resume actions, active counts, and acquisition limits shared across workers;
• job retry and cancellation, and batch cancellation;
• batch progress and a live dependency-graph viewer;
• live updates over Server-Sent Events; and
• application-defined links to traces and logs.

Job search and filters are paged on the server in groups of 50. Pending jobs show “Paused” while acquisition for their definition is paused. Job details include current definition configuration below the payload, with its queue and pause status. The header shows the job name, invocation ID, status, and actions. Job links support opening details in a new tab. Batch members link back to their workflow.

Definitions can be filtered live by name, queue, or tag. Their Concurrency column lists only configured limits with current active-job and fixed/sliding acquisition counts; unbounded definitions show “No limit” once. Window counts include retries and expired-lease reacquisitions, and remain visible while paused.

Monitoring refresh

GET api/overview and SSE share the live snapshot: counts, servers, job acquisition states and recurring pause/progress. GET api/definitions provides job and recurring configuration separately. The client shares the snapshot across pages and retains metadata for five minutes, polling it on that interval while definitions, recurring schedules, or job definition details are in use. Disconnected live status polls every five seconds. Metadata is not included in every SSE update.

Identifier fields

Dashboard JSON uses jobHandle for job records and batchHandle for batch records. Their values remain opaque JSON strings. The .NET monitoring APIs use JobHandle and BatchHandle so a job ID cannot be passed to a batch operation by mistake:

var job = await monitor.GetJobAsync(
	JobHandle.FromString(jobHandle),
	cancellationToken);

var batch = await monitor.GetBatchAsync(
	BatchHandle.FromString(batchHandle),
	cancellationToken);

The handle converters keep the HTTP representation string-based. In .NET, first take the handle from the record, then read its .JobHandle or .BatchHandle string when building a route or an external-system query.

Telemetry links

Telemetry destinations are application-defined because Aspire, Jaeger, Grafana, Seq, Azure Monitor, and other systems use different query URLs. Register callbacks for execution traces, execution logs, or a stable job-level query across all retries:

var traceExplorer = new Uri("https://traces.example/");
var logExplorer = new Uri("https://logs.example/");

builder.Services.AddMyAppJobs()
	.ConfigureStorage(storage => storage.UseInMemory())
	.AddImmediateJobsDashboard()
	.ConfigureDashboard(options => options.AuthorizationPolicy = "operations")
	.AddTelemetryLink(
		"View execution trace",
		JobTelemetryLinkKind.Trace,
		context => context.Execution?.ExecutionTraceId is { } traceId
			? new(traceExplorer, $"trace/{traceId}")
			: null)
	.AddTelemetryLink(
		"View execution logs",
		JobTelemetryLinkKind.Logs,
		context =>
		{
			var jobHandle = context.Job.JobHandle;
			return context.Execution is { } execution
				? new(logExplorer,
					$"search?jobHandle={Uri.EscapeDataString(jobHandle.JobHandle)}&attempt={execution.Attempt}")
				: null;
		})
	.AddTelemetryLink(
		"View all retry logs",
		JobTelemetryLinkKind.Logs,
		context =>
		{
			var jobHandle = context.Job.JobHandle;
			return context.Execution is null
				? new(logExplorer, $"search?jobHandle={Uri.EscapeDataString(jobHandle.JobHandle)}")
				: null;
		});

Each execution attempt creates a distinct Activity linked to the enqueue context. Every acquired execution is retained with its outcome, worker, timing, trace and span identifiers, and full failure text until purged. Batches can be canceled, but are only removed by the regular retention purge.

The job-detail timeline is newest first. Job-level callbacks receive Execution = null, which is useful for links that search by the stable job ID across all retries. Execution-level callbacks receive the exact retained attempt, including its attempt number, trace and span IDs, and timing.

AddTelemetryLink callbacks may return null when a destination does not apply and may return HTTP(S) or dashboard-relative URLs.

More information

• Immediate.Jobs core package
• Dashboard and monitoring documentation
• Aspire sample
• GitHub repository