Monitoring setup guide

This guide helps you add or change uptime checks for any project (Next.js on Vercel, APIs on Fly.io, static sites, etc.). The running app reads data/monitors.json unless the MONITORS_JSON environment variable is set.

In the deployed app: open /setup for this same document (readable in the browser).

Five-minute checklist

1. Choose where config lives
   • Git + redeploy: edit data/monitors.json in this repo (good for stable public URLs).
   • Vercel only: set env var MONITORS_JSON to a single-line JSON array (good for secrets or URLs you do not want in git).
2. Add one row per check — at minimum id, name, and url (see Field reference).
3. Validate locally: npm run validate:monitors (checks JSON shape and required fields).
4. Smoke-test: npm run dev → open / and confirm each row goes green (or adjust expectedStatus / method).
5. Deploy — push to GitHub and let Vercel build; confirm / and /setup on production.

Two ways to configure monitors

A. File in the repo (default)

• Path: data/monitors.json
• Must be a JSON array of monitor objects.
• Optional: copy from data/monitors.example.json as a template, then rename/replace URLs.
• IDE hints: VS Code / Cursor can validate against data/monitors.schema.json (see Editor integration).

B. Environment variable MONITORS_JSON (Vercel / other hosts)

• In the Vercel project → Settings → Environment Variables, add MONITORS_JSON.
• Value must be a valid JSON array (same shape as the file). Often pasted as one line to avoid newline issues.
• When MONITORS_JSON is non-empty, the app ignores data/monitors.json for that deployment.

Field reference

Probe behavior: the checker uses fetch with redirect: "follow" and a small User-Agent string. It does not parse JSON bodies; health is determined by HTTP status (and absence of network errors).

Choosing URLs for common stacks

Default sample: three products (today)

The checked-in data/monitors.json is a multi-app smoke set aligned with xingai-invest-ai/docs/deploy/release-runbook.md (Vercel project list + Fly backend):

Edit or delete rows if you only want one product, or point URLs at staging.

Invest AI (detail)

Duplicate or edit rows if your canonical frontend URL is not the default Vercel preview hostname.

Validate before deploy

npm run validate:monitors

This runs a small Node script that:

• Parses data/monitors.json
• Ensures each entry has id, name, url (non-empty strings)
• Checks optional fields have sensible types

It does not perform live HTTP checks (use the dashboard for that).

Editor integration (JSON Schema)

In VS Code / Cursor, add (or merge) into .vscode/settings.json:

{
  "json.schemas": [
    {
      "fileMatch": ["data/monitors.json", "data/monitors.example.json"],
      "url": "./data/monitors.schema.json"
    }
  ]
}

This repository includes .vscode/settings.json with that rule preconfigured when you open the xingai-ops-status folder.

Troubleshooting

中文说明（快速对照）

• 配置位置二选一： 仓库里的 data/monitors.json，或 Vercel 环境变量 MONITORS_JSON（整段 JSON 数组，常写成一行）。
• 必填字段： id、name、url；其余见上表。
• 本地校验： 执行 npm run validate:monitors。
• 看板与文档： 浏览器打开 / 看状态，打开 /setup 阅读本指南。
• Worker 无独立 HTTP 时： 用「能读到 worker 写入数据」的 API URL 作为间接探活，并在 notes 里写清楚含义。

Related files in this repo