Monitoring & Hooks

Read live queue health straight from the FlexiQ handle — no extra service. The same data powers the dashboard and the CLI read commands.

Stats

Counts by status, globally or per queue:

QueueStats stats = flexiq.stats(); // pending, running, completed, failed, dead, cancelled
flexiq.statsByQueue("default");
flexiq.statsAllQueues();           // Map<String, QueueStats>

Metrics

metrics(taskName, sinceMs) returns the raw per-execution records within a trailing window — wall time, memory, and success flag for each finished attempt. Pass null as the task name for all tasks:

List<TaskMetric> lastHour = flexiq.metrics(null, 3_600_000L);
for (TaskMetric m : flexiq.metrics("add", 3_600_000L)) {
    System.out.println(m.taskName + " " + m.wallTimeNs / 1_000_000 + "ms ok=" + m.succeeded);
}

Each TaskMetric carries taskName, jobId, wallTimeNs (nanoseconds), memoryBytes, succeeded, and recordedAt. Aggregation (percentiles, rates) is up to you — or plug in Micrometer for a ready-made timer per task.

Error history

Per-attempt failures for one job:

List<JobError> errors = flexiq.jobErrors(jobId); // attempt, error, failedAt

Workers

Each running worker registers and heartbeats; list the live fleet:

for (WorkerInfo w : flexiq.listWorkers()) {
    System.out.println(w.workerId + " " + w.hostname + " " + w.status
            + " threads=" + w.threads + " beat=" + w.lastHeartbeat);
}

A worker appears while it heartbeats (lastHeartbeat is Unix milliseconds); stop() unregisters it. See Deployment for the worker lifecycle.

Health & readiness

Health.check() and Health.readiness(flexiq) are standalone — no dashboard, no HTTP server. Wire them into whatever already serves your probes, or call them from a script:

import org.byteveda.flexiq.health.Health;
import org.byteveda.flexiq.health.ReadinessReport;

Health.check();                                  // HealthReport[status=ok] — liveness, never touches storage

ReadinessReport report = Health.readiness(flexiq);
report.ready();                                  // true only when every check passed
report.toMap();
// {
//   "status": "ready",
//   "checks": {
//     "storage": "ok",
//     "workers": { "count": 2, "status": "ok" },
//     "resources": { "count": 1, "unhealthy": [], "status": "ok" }
//   }
// }

Health.readiness never throws: a dependency that fails is reported as "error: <message>" in checks and degrades the overall status, so a probe endpoint can always answer. The resources check is omitted when no worker advertises a worker resource; when one does, it is built from Health.resourceStatus(flexiq), which aggregates per-resource health across every live worker's heartbeat.

Serve them behind your own routes — return 503 on degraded so orchestrators drain the instance:

ReadinessReport report = Health.readiness(flexiq);
int status = report.ready() ? 200 : 503;

The dashboard serves these same helpers on /health and /readiness.

Metrics scraping & tracing

For meters and distributed traces, the contrib integrations wrap the middleware layer:

• Micrometer — one Observation per execution: a timer plus a trace span, exported by whatever backend your registry is wired to.
• Sentry — error capture.