Checking a deployment
The two health check addresses, the Health page, the This install card, log files and Seq.
There are four places to look when you want to know whether your Modbot is working:
- two health check addresses your hosting platform can call,
- the Health page in the web app,
- the This install card in Settings,
- the logs, which you can read in the app on the Modbot's log page.
Modbot can also email you when something goes wrong, rather than waiting for you to look. See Alerts by email.
Health check addresses
Modbot answers two addresses. Neither needs you to be signed in.
/health/live
Answers Healthy as long as the Modbot process is running. It checks nothing else, on purpose: if
it checked the database, a platform would restart Modbot every time the database blinked, which is
exactly when you want Modbot up to read the error.
Use it for checks that restart a container that has stopped responding. The Docker image's own health check calls it every 30 seconds.
/health/ready
Answers whether Modbot can reach its database right now. The reply names the check:
{
"status": "Healthy",
"checks": {
"database": {
"status": "Healthy",
"description": "Database is reachable."
}
}
}When the database cannot be reached, status is Unhealthy, the description says
Database is not reachable., and the HTTP status is 503.
Use it to decide when a new deployment is ready for traffic. Railway's configuration for Modbot uses this one, with a 300 second timeout. See Railway.
Nothing answers during startup
Modbot updates its database tables before it starts listening. Until that is done, neither address answers. On a first deploy this can take a little while. See PostgreSQL.
The Health page
Health opens from the status rows at the bottom of the sidebar. You need the See the operational log permission, which is also what makes those rows appear.
Each row is a part of Modbot and one word for how it is doing: VRChat, Discord, Database, Sync, and AI once this deployment is using it. Clicking a row opens this page at that part's card.
The page refreshes itself every 20 seconds. It is a stack of cards. Five are always there — VRChat, Database, What Modbot reads, VRChat request limits and Kinds of audit log entry Modbot does not know. The rest appear only when they have something to say, so a Modbot with nothing wrong shows a short page. From top to bottom:
Demo data
Only on a demo Modbot, and only while it is still building its example data. It shows how far it has got.
Alerts
One row for each thing Modbot is currently unhappy about. Nothing is shown when there is nothing.
VRChat
Whether Modbot is reaching VRChat, as one of:
| Status | What it means |
|---|---|
| Working | Requests are going through. |
| Waiting on purpose | Modbot has stopped sending for a while: it is waiting out a rate limit, or waiting before it may sign in again. It recovers by itself. Do not restart Modbot to hurry it. |
| Needs you | Something will not fix itself: Cloudflare is blocking this host, the VRChat account cannot read the group, or a kind of request has stopped after being rate limited again and again. The line below says which. |
| Not configured | No VRChat account has been set up yet. |
Under it: Last signed in, Sign-ins this hour (out of the limit Modbot allows itself), and Next sign-in when Modbot is waiting before it may sign in again.
To change the VRChat account or the proxy, go to Settings, Modbot's VRChat login.
Database
Whether Modbot can reach its database: online, or unreachable when the process is up and the
database is not. It is the same answer /health/ready gives.
Under it, Sync is not running in this process. appears when this copy of Modbot answers the web app but does not read from VRChat.
AI spend
Shown only when an AI spending limit is close or reached. See Limits and spend.
AI
Shown when AI calls have been failing, timing out or falling back in the last hour: how many calls there were, how many failed, how many timed out, how many used the backup model, and which model is answering now.
Shown when any email is queued or has failed: how many are waiting, when the next one goes, and how many failed. See The email limit.
Modbot's log
Stored says whether log lines are being written to the database, how many have been written, and how many were dropped. To Modbot Cloud says Off, or when the last batch was sent, how many are waiting and how many were dropped. See Logs.
Discord bot
Shown when relevant. The bot is not set up, connecting, working, reconnecting, or stopped — needs you. When something is wrong it lists channels the bot cannot post in and the Discord permissions it is missing, and Intents off in the Developer Portal if Discord is not sending it what it needs. See Setting up the bot.
Calendar
Shown only when a planned event failed to reach VRChat's calendar or Discord, or its instance did not open, or a place an event wants is Not set up (no managed group or VRChat account for VRChat, no server id or no connected bot for Discord). A Missing Create Events, Missing Manage Events or Missing Create Events and Manage Events line in the Discord bot card means an event wants a Discord event and the bot cannot make one. See Calendar.
Paused moderation rules
One row for each AutoMod rule that has stopped itself, with the reason and how long ago. See If a rule runs away.
What Modbot reads
The jobs that read from VRChat: Group audit log, Group info, User profiles, User details, Member list and Ban list. Each says when it was last checked and how its last run went. A line underneath says whether the audit log catch-up has finished, and how far it has read.
Modbot Cloud
Whether this Modbot's usage report reached Modbot Cloud: Sent, Failed or Not sent yet, with
when it went, the address it used, and the reason if it failed. It says Off when Send usage
report to Modbot Cloud in Settings, Server is switched off. The part is left out when
MODBOT_CLOUD_DISABLED is set.
VRChat request limits
One row per kind of VRChat request: Limit names it, Requests a second is its current rate, Speed is its pace as a multiple of the normal one (below 1.00× when Modbot has slowed it down), Times refused is how many times VRChat has said "too many requests", and State is running, stopped (paused until the time shown) or given up, needs you.
Kinds of audit log entry Modbot does not know
Kinds of entry from your group's audit log that Modbot has no meaning for yet, with how many it has seen. None seen. is the normal answer.
The This install card
Settings, Server, This install describes what is running. The Server tab needs the Change settings permission.
| Row | What it shows |
|---|---|
| Version | The release version, as year.month.patch. |
| Version commit | The first 7 characters of the git commit the build came from. Point at it to see the whole id. Unknown if the build was not told. |
| Release branch | The branch the build came from, or Unknown. |
| Host | The hosting platform Modbot recognised, such as Railway, or self-hosted. |
| Log files | Written to disk, or Console and Seq only if the log directory cannot be written to. |
When you report a problem, include the version and the commit.
Logs
The console
Modbot prints its main log to the console at Information level and above. This is what your hosting
platform's log view shows, and what docker logs shows. The first lines of every start say which port
Modbot is using, which host it thinks it is on, and whether its log directory has survived a
restart. After that it is the record of what Modbot did — syncs, moderation, settings changed.
A request that failed or answered a 5xx is a warning and is always shown. The rest are at Debug,
along with the database queries, so set LOG_LEVEL=Debug for a line per request with the method,
path, status and how long it took. See
Logs.
CONSOLE_LOG_MODE chooses the shape: serilog for readable lines (the default), json for
Serilog's compact JSON, and railway_json for the JSON Railway parses into structured logs.
LOG_LEVEL sets the lowest level written. See
Console log modes.
Log files
Modbot writes log files into /app/logs in the container. Every start gets its own files, named with
the date and the start time:
| File | What is in it |
|---|---|
modbot_log_<date>_<time>.txt and .jsonl | The main record, Information level and above. |
modbot_log_http_<date>_<time>.txt and .jsonl | Only the requests Modbot sends to outside services, such as VRChat. |
modbot_log_debug_<date>_<time>.txt and .jsonl | Everything, in detail. Only written when MODBOT_DEBUG_LOGGING is on. |
The .txt files are for reading. The .jsonl files hold the same events with every detail kept
separately, for searching with a tool.
A file starts a new part when it reaches 64 MB. Modbot keeps the newest 60 main files, 60 HTTP files and 6 debug files, and deletes older ones.
Files that do not survive. On a platform that throws the container's disk away on redeploy, these
files go with it. Modbot writes them anyway and logs a warning at startup, because you may have
mounted a volume it cannot see yet. Once a restart shows the directory lasted, the warning stops. To
keep logs, mount a volume at /app/logs or set SEQ_URL.
Files that cannot be written. If /app/logs cannot be written to, Modbot writes no files, logs
Log files are not being written., and the Log files row says Console and Seq only.
Seq
Set SEQ_URL to the address of a Seq server and Modbot sends its logs
there as well, with every detail searchable. This is the one logging setting kept outside the
database, because it is how you find out why Modbot cannot reach its database. With
MODBOT_DEBUG_LOGGING on, Seq also gets the Debug detail.
The database
Modbot also keeps the same lines in its own database, and the Modbot's log page in the app reads them, so a deployment with no Seq and no disk can still search its log. See Logs.