System Endpoints

Endpoint overview

Server / all mode

Endpoint	Purpose	Auth
GET /healthz	liveness probe	none
GET /readyz	readiness probe	none
GET /metrics	Prometheus metrics for the main HTTP process	none

Worker-only mode

Endpoint	Purpose	Auth
GET :WORKER_METRICS_PORT/healthz	liveness for worker-only mode	none
GET :WORKER_METRICS_PORT/metrics	Prometheus metrics for worker-only mode	none

For the defaults and validation rules of WORKER_METRICS_PORT, see Configuration.

GET /healthz

As long as the process is alive, this endpoint returns:

HTTP/1.1 200 OK
Content-Type: application/json

{"status":"ok"}

The worker-only listener at GET :WORKER_METRICS_PORT/healthz uses the same JSON shape.

Use it for liveness, not dependency readiness.

/healthz and /readyz are intentionally different

/healthz only tells you the process is alive. A 200 here does not imply PostgreSQL, Redis, or buckets are reachable.

GET /readyz

/readyz checks all critical dependencies within a 2-second timeout:

• PostgreSQL
• Redis
• source bucket
• media bucket

curl example

curl -i http://localhost:3000/readyz

Success:

HTTP/1.1 200 OK
Content-Type: application/json

{"status":"ok"}

Failures return 503 Service Unavailable with a structured JSON summary plus per-check results. Vylux does not stop at the first failed dependency; it reports every readiness check it evaluated during the request.

{
	"status": "not_ready",
	"error": "readiness checks failed",
	"checks": [
		{"name": "postgres", "status": "ok"},
		{
			"name": "redis",
			"status": "failed",
			"error": "dial tcp 127.0.0.1:6381: connect: connection refused"
		},
		{
			"name": "source bucket",
			"status": "failed",
			"error": "source storage is not configured"
		},
		{
			"name": "media bucket",
			"status": "failed",
			"error": "media storage is not configured"
		}
	]
}

Failure body fields

Field	Meaning
status	overall readiness state; currently not_ready on failure
error	short summary of the failed readiness evaluation
checks[].name	the dependency name such as postgres, redis, source bucket, or media bucket
checks[].status	ok or failed
checks[].error	present only when that dependency failed

/readyz is a dependency probe

If /readyz fails while /healthz succeeds, treat it as an infrastructure or configuration problem first, not as an HTTP routing problem.

GET /metrics

The main HTTP process exposes Prometheus metrics at /metrics. The most useful metric families include:

• vylux_http_requests_total
• vylux_http_request_duration_seconds
• vylux_image_cache_events_total
• vylux_image_results_total
• vylux_image_errors_total
• vylux_worker_tasks_total
• vylux_worker_task_duration_seconds
• vylux_readiness_failures_total
• vylux_queue_tasks
• vylux_queue_metrics_sync_failures_total

curl example

curl -s http://localhost:3000/metrics | rg '^vylux_'

Worker-only metrics listener

When Vylux runs in --mode=worker, it starts a lightweight listener on WORKER_METRICS_PORT:

• default port: 3001
• endpoints: /healthz and /metrics
• set WORKER_METRICS_PORT=0 to disable it

This is useful when server and worker run as separate deployments and need separate probes and scraping targets.

Worker-only mode does not expose /readyz

When Vylux runs in --mode=worker, use :WORKER_METRICS_PORT/healthz for liveness and rely on external dependency monitoring for deeper readiness signals.

Tracing headers

Beyond metrics, Vylux also propagates tracing through:

• traceparent
• tracestate
• X-Trace-ID

X-Trace-ID is mainly for operator-visible logs and manual correlation. The authoritative trace context is the W3C Trace Context headers.