diff --git a/src/content/self-host/workers/health-checks.mdx b/src/content/self-host/workers/health-checks.mdx new file mode 100644 index 0000000..c3d0ccb --- /dev/null +++ b/src/content/self-host/workers/health-checks.mdx @@ -0,0 +1,10 @@ +--- +title: "Health Checks" +description: "Expose a health endpoint for worker liveness and readiness probes." +--- + +Health checks verify that a worker is healthy, including its connection to the Rivet control plane. + +Mount `registry.routes.health()` in your HTTP router. For example, with Hono: `app.get("/health", () => registry.routes.health())`. + +A healthy worker returns `200` with its status, runtime, and version. If its connection to the control plane is unhealthy, it returns `503`. Point your liveness and readiness probes at the mounted path. diff --git a/src/content/self-host/workers/metadata.mdx b/src/content/self-host/workers/metadata.mdx new file mode 100644 index 0000000..8299984 --- /dev/null +++ b/src/content/self-host/workers/metadata.mdx @@ -0,0 +1,10 @@ +--- +title: "Metadata" +description: "Expose RivetKit runtime metadata from a worker." +--- + +Exposing worker metadata is optional, but useful for verifying the RivetKit version and actor types running on a worker. + +Mount `registry.routes.metadata()` in your HTTP router. For example, with Hono: `app.get("/metadata", () => registry.routes.metadata())`. + +The endpoint returns the worker's runtime version, registered actor names, and connection metadata as JSON. diff --git a/src/content/self-host/workers/production-checklist.mdx b/src/content/self-host/workers/production-checklist.mdx index 6e10ead..f4b4b7c 100644 --- a/src/content/self-host/workers/production-checklist.mdx +++ b/src/content/self-host/workers/production-checklist.mdx @@ -15,6 +15,11 @@ Split by runtime mode, because the two halves barely overlap. A reader on a serv - **Ensure log level is not set to debug.** Leave `RIVET_LOG_LEVEL` at its default or explicitly set it to `warn` to avoid excessive logging. - **Do not set `RIVET_EXPOSE_ERRORS=1` in production.** This exposes internal error details to clients. It is automatically enabled when `NODE_ENV=development`. +## Monitoring + +- **Configure health probes.** Mount `registry.routes.health()` and verify your liveness and readiness probes receive `200`. See Health Checks. +- **Scrape Prometheus metrics.** This is recommended for monitoring worker performance and failures. See Prometheus Metrics. + ## Runtime Mode - **Configure a runner version.** Required for graceful upgrades and draining of old actors. Applies to both serverless and runner modes. diff --git a/src/content/self-host/workers/prometheus-metrics.mdx b/src/content/self-host/workers/prometheus-metrics.mdx new file mode 100644 index 0000000..be49575 --- /dev/null +++ b/src/content/self-host/workers/prometheus-metrics.mdx @@ -0,0 +1,12 @@ +--- +title: "Prometheus Metrics" +description: "Expose and scrape process-wide RivetKit metrics from a worker." +--- + +RivetKit exposes Prometheus metrics that help diagnose actor activity, networking, SQLite behavior, and more. + +Mount `registry.routes.prometheusMetrics()` in your HTTP router. For example, with Hono: `app.get("/metrics", (c) => registry.routes.prometheusMetrics(c.req.raw))`. + +Configure Prometheus to scrape the mounted path on every worker instance. + +By default, this endpoint is exposed without authentication. If your metrics may contain private information, protect it with a token or expose it only on a private router or network. diff --git a/src/sitemap/deployMatrix.ts b/src/sitemap/deployMatrix.ts index c7fe8b9..76254c7 100644 --- a/src/sitemap/deployMatrix.ts +++ b/src/sitemap/deployMatrix.ts @@ -63,7 +63,13 @@ export function platformsFor( * Non-platform pages in each section. Platform guides are appended after these * by the sidebar builder and the route. */ -export const WORKER_PAGES = ["index", "production-checklist"] as const; +export const WORKER_PAGES = [ + "index", + "production-checklist", + "health-checks", + "metadata", + "prometheus-metrics", +] as const; export const CONTROL_PLANE_PAGES = [ "index", diff --git a/src/sitemap/self-host.ts b/src/sitemap/self-host.ts index 94da999..e358033 100644 --- a/src/sitemap/self-host.ts +++ b/src/sitemap/self-host.ts @@ -23,8 +23,8 @@ const PAGE_TITLES: Record = { }; /** - * The Self-Host tab's sidebar, derived entirely from `deployMatrix`. All four - * products get the same shape; only the platform lists differ. + * The Self-Host tab's sidebar. All four products get the same shape; only the + * platform lists derived from `deployMatrix` differ. */ export function deploySidebar(productId: string): SidebarItem[] { const base = `/${productId}/self-host`; @@ -100,5 +100,29 @@ export function deploySidebar(productId: string): SidebarItem[] { }, ], }, + { + title: "Reference", + pages: [ + { + title: "Workers", + icon: faSliders, + collapsible: true, + pages: [ + { + title: "Health Checks", + href: `${base}/workers/health-checks/`, + }, + { + title: "Metadata", + href: `${base}/workers/metadata/`, + }, + { + title: "Prometheus Metrics", + href: `${base}/workers/prometheus-metrics/`, + }, + ], + }, + ], + }, ]; }