Skip to main content

系統端點

端點總覽​

Server / all mode​

Endpoint用途Auth
GET /healthzliveness probe無
GET /readyzreadiness probe無
GET /metrics主 HTTP process 的 Prometheus metrics無

Worker-only mode​

Endpoint用途Auth
GET :WORKER_METRICS_PORT/healthzworker-only process 的 liveness無
GET :WORKER_METRICS_PORT/metricsworker-only process 的 Prometheus metrics無

WORKER_METRICS_PORT 的預設值與驗證規則，請見 設定。

GET /healthz​

只要 process 活著就回：

200 OK
OK

適合用於 liveness probe，不代表下游依賴已就緒。

/healthz 與 /readyz 本來就代表不同意義

/healthz 只表示 process 還活著。這裡回 200，不代表 PostgreSQL、Redis 或 buckets 一定可連。

GET /readyz​

/readyz 會在 2 秒 timeout 內依序檢查：

  • PostgreSQL
  • Redis
  • source bucket
  • media bucket

curl 範例​

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

成功：

200 OK
OK

失敗時會回 503 Service Unavailable，body 會指出是哪個依賴失敗，例如：

not ready: redis: dial tcp 127.0.0.1:6381: connect: connection refused
/readyz 是依賴探針

如果 /healthz 成功但 /readyz 失敗，優先把它當成基礎設施或設定問題，而不是 HTTP 路由問題。

GET /metrics​

主 HTTP process 的 metrics 由 /metrics 暴露。典型 metric families 包括：

  • 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 範例​

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

worker-only metrics listener​

當你以 --mode=worker 啟動 Vylux，worker 會另外開一個輕量 listener：

  • port：WORKER_METRICS_PORT，預設 3001
  • endpoints：/healthz、/metrics
  • WORKER_METRICS_PORT=0 時停用

這讓 K8s 或其他平台可以把 worker 跟 HTTP server 分開探測與抓取 metrics。

worker-only mode 不會暴露 /readyz

當 Vylux 以 --mode=worker 運行時，請用 :WORKER_METRICS_PORT/healthz 做 liveness，較深層的 readiness 則交給外部依賴監控。

追蹤 header​

除了 metrics 外，HTTP request 與 webhook/callback 也會攜帶 tracing 資訊：

  • traceparent
  • tracestate
  • X-Trace-ID

X-Trace-ID 適合人工除錯與日誌關聯；真正的 trace context 仍以 W3C Trace Context headers 為主。