On this page

Cortex

Monitoring API

A Cortex worker runs a lightweight monitoring HTTP server exposing liveness, readiness and Prometheus metrics endpoints, designed for Kubernetes probes, load balancers and metrics scrapers. Loom exposes a health check on its REST API and its own Prometheus metrics endpoint on a dedicated monitoring port.

This page covers health and readiness. The full metric catalogs live on their own pages: Loom Metrics and Cortex Metrics.

Cortex Health Server

The Cortex daemon starts a small Vert.x HTTP server (separate from any Loom traffic) on port 8093 by default, configurable with the CORTEX_MONITORING_PORT environment variable.

Endpoint Status Meaning

GET /api/health

always 200 while the process is up

Liveness. JSON { "status": "up", "loom": { … } } — the process is alive.

GET /api/ready

200 when ready, else 503

Readiness. Ready means the worker is connected to Loom and registered. JSON { "status": "ready" | "not_ready", "loom": { … } }.
Note
 The legacy paths GET /health and GET /ready are also served for backward compatibility with existing probes.

The embedded loom object reports the worker’s connection to Loom:

{
  "status": "ready",
  "loom": {
    "configured": true,
    "connected": true,
    "registered": true,
    "host": "loom.internal",
    "port": 8092,
    "reconnectAttempts": 0,
    "lastConnectedAt": 1750000000000,
    "lastHeartbeatAckAt": 1750000009000,
    "error": null
  }
}

Until the worker has both connected and registered, it reports up for liveness but stays not_ready — the loom object tells you which step is missing (connected, registered, reconnectAttempts, error).

Kubernetes Probe Configuration

Map liveness onto /api/health and readiness onto /api/ready:

livenessProbe:
  httpGet:
    path: /api/health
    port: 8093
  initialDelaySeconds: 10
  periodSeconds: 15

readinessProbe:
  httpGet:
    path: /api/ready
    port: 8093
  initialDelaySeconds: 5
  periodSeconds: 10

Changing the Port

CORTEX_MONITORING_PORT=9090

Loom Health Check

The Loom server exposes a health check on its REST API:

GET /api/v1/health
{
  "status": "UP",
  "version": "1.0.0-SNAPSHOT",
  "database": "UP",
  "timestamp": "2026-07-25T20:00:00Z"
}

It verifies database connectivity; if the database is unreachable, database is DOWN and status becomes DEGRADED. See REST API.

Prometheus Metrics

Both components expose a Prometheus scrape endpoint at GET /metrics on their monitoring port — never on the REST API port. The response is standard Prometheus text format and includes JVM and process metrics (memory, GC, threads, CPU) alongside MetaLoom’s own application metrics.

Component Endpoint Port

Cortex

GET /metrics

8093 (CORTEX_MONITORING_PORT) — shared with the health server

Loom

GET /metrics

8989 (LOOM_SERVER_MON_PORT) — a dedicated monitoring server

The endpoints are unauthenticated and intended for an internal Prometheus scraper; restrict access to the monitoring ports at the network layer. A scrape of Loom’s REST port (8092) returns 404 — metrics live only on the monitoring port.

Example Prometheus scrape config

scrape_configs:
  - job_name: metaloom-loom
    static_configs:
      - targets: ["loom.internal:8989"]
  - job_name: metaloom-cortex
    static_configs:
      - targets: ["cortex-1.internal:8093", "cortex-2.internal:8093"]

Metric catalogs

The individual meters, their labels and example PromQL queries are documented per component:

  • Loom Metrics — pipeline runs, task dispatch, results, worker fleet, leases, event fan-out and auth failures (loom_*).

  • Cortex Metrics — Loom connection state, tasks, node operations, result egress, AI-model calls and worker resources (cortex_*).

Changing the Loom monitoring port

LOOM_SERVER_MON_PORT=9091

Looking for something else?

All documentation Feature overview