Prometheus Metrics

Java has no Prometheus contrib. Metrics come from Micrometer: the FlexiQObservation middleware wraps each task execution in a Micrometer Observation, which a PrometheusMeterRegistry turns into a timer (and, if you add a tracing bridge, a span). See the dedicated Micrometer guide for the full API.

Setup

The SDK compiles against io.micrometer:micrometer-observation as compileOnly, so add it plus a Prometheus registry to your build:

• io.micrometer:micrometer-observation
• io.micrometer:micrometer-registry-prometheus (brings micrometer-core, which provides DefaultMeterObservationHandler and PrometheusMeterRegistry)

import io.micrometer.core.instrument.observation.DefaultMeterObservationHandler;
import io.micrometer.observation.ObservationRegistry;
import io.micrometer.prometheusmetrics.PrometheusConfig;
import io.micrometer.prometheusmetrics.PrometheusMeterRegistry;
import org.byteveda.flexiq.contrib.FlexiQObservation;

PrometheusMeterRegistry prometheus = new PrometheusMeterRegistry(PrometheusConfig.DEFAULT);
ObservationRegistry observations = ObservationRegistry.create();
observations.observationConfig()
        .observationHandler(new DefaultMeterObservationHandler(prometheus));

flexiq.use(new FlexiQObservation(observations));

What's emitted

Each execution attempt starts an observation named flexiq.task (customizable via new FlexiQObservation(registry, name, taskFilter)) tagged with flexiq.task = the task name. Micrometer's meter handler converts it into a timer on the Prometheus registry; the exposed series name and suffixes follow Micrometer's Prometheus naming convention (dots become underscores, a _seconds suffix is added), not a fixed flexiq_* name from the contrib. Retries are separate attempts, each producing its own observation.

Exposing metrics

Serve prometheus.scrape() from any HTTP endpoint, or use Spring Boot Actuator's /actuator/prometheus, which wires the registry for you. The flexiq_jobs_total / flexiq_dlq_size names and the polled queue-depth gauges below are Python/Node only — build Java dashboards and alerts on the timer series your Micrometer→Prometheus registry emits.

pip install flexiq[prometheus]

This installs prometheus-client as a dependency.

Peer dependency: prom-client. Import from the flexiq/contrib/prometheus subpath — it is not exported from the main barrel.

The first four are written by PrometheusMiddleware as each job runs; the last three are polled by PrometheusStatsCollector. Metrics are created once per namespace and reused, so it's safe to construct the middleware and the collector independently as long as they share a namespace.

Add PrometheusMiddleware to your queue to track per-task execution metrics:

from flexiq import Queue
from flexiq.contrib.prometheus import PrometheusMiddleware

queue = Queue(db_path="myapp.db", middleware=[PrometheusMiddleware()])

PrometheusMiddleware(
    namespace="myapp",
    disabled_metrics={"resource", "proxy"},
    task_filter=lambda name: not name.startswith("internal."),
)

Register prometheusMiddleware to record per-job counters and the duration histogram:

import { prometheusMiddleware } from "@byteveda/flexiq/contrib/prometheus";

queue.use(prometheusMiddleware());

For queue-level metrics, use the stats collector. It polls queue.stats() (and resource/proxy/interception stats) on a background thread:

from flexiq.contrib.prometheus import PrometheusStatsCollector

collector = PrometheusStatsCollector(queue, interval=10)
collector.start()

PrometheusStatsCollector(
    queue,
    interval=10,
    namespace="myapp",
    disabled_metrics={"intercept"},
)

Call collector.stop() on shutdown — it signals the background thread and joins it (up to 5s).

PrometheusStatsCollector polls queue depth and DLQ size on an interval:

import { PrometheusStatsCollector } from "@byteveda/flexiq/contrib/prometheus";

const collector = new PrometheusStatsCollector(queue);
collector.start();

The internal timer is unref'd, so it never keeps the process alive on its own. Call .stop() on graceful shutdown:

process.on("SIGTERM", () => {
  collector.stop();
  worker.stop();
});

Start a standalone /metrics endpoint for Prometheus to scrape:

from flexiq.contrib.prometheus import start_metrics_server

start_metrics_server(port=9090)

This uses prometheus_client.start_http_server under the hood.

This is a different /metrics than the dashboard's

start_metrics_server opens its own dedicated HTTP server — it is not the same endpoint as the dashboard's GET /metrics (see REST API). Both ultimately call prometheus_client.generate_latest(), but each only serves metrics registered in its own process:

• Run start_metrics_server in the same process as your PrometheusMiddleware / PrometheusStatsCollector (typically the worker process) — this is the endpoint you'll usually scrape.
• The dashboard's GET /metrics only shows something useful if the dashboard process itself registered metrics (e.g. it also runs PrometheusMiddleware). If your worker and dashboard run as separate processes — the common deployment — scrape the worker's start_metrics_server instead.

There's no standalone metrics server built in — mount the registry on your own HTTP server:

import { register } from "prom-client";
import express from "express";

const app = express();
app.get("/metrics", async (_req, res) => {
  res.set("Content-Type", register.contentType);
  res.end(await register.metrics());
});

• Throughput — rate(flexiq_jobs_total[5m]) by task and status
• Duration p95 — histogram_quantile(0.95, rate(flexiq_job_duration_seconds_bucket[5m]))
• Queue depth — flexiq_queue_depth by queue
• DLQ size — flexiq_dlq_size with an alert threshold
• Worker utilization — flexiq_worker_utilization by queue

• Throughput — rate(flexiq_jobs_total[5m]) by task and status
• Duration p95 — histogram_quantile(0.95, rate(flexiq_job_duration_seconds_bucket[5m]))
• Queue depth — flexiq_queue_depth by queue
• DLQ size — flexiq_dlq_size with an alert threshold

Java exports metrics through Micrometer, not this contrib — the metric names in these rules don't exist there. Build the equivalent alerts on the names your Micrometer→Prometheus registry emits instead.

PrometheusMiddleware composes with other middleware:

from flexiq.contrib.otel import OpenTelemetryMiddleware
from flexiq.contrib.sentry import SentryMiddleware

queue = Queue(
    db_path="myapp.db",
    middleware=[
        OpenTelemetryMiddleware(),
        PrometheusMiddleware(),
        SentryMiddleware(),
    ],
)

See the Middleware guide for more on combining middleware.

prometheusMiddleware composes with other middleware — register each with its own queue.use() call, in the order you want their hooks to run:

import { otelMiddleware } from "@byteveda/flexiq/contrib/otel";
import { sentryMiddleware } from "@byteveda/flexiq/contrib/sentry";
import { prometheusMiddleware } from "@byteveda/flexiq/contrib/prometheus";

queue.use(otelMiddleware());
queue.use(prometheusMiddleware());
queue.use(sentryMiddleware());

See Middleware for more on hook ordering.