Self-hosted support bundle
Produce a support bundle of setting names, versions, health checks and counters with one command, see every field it holds, and send it by email or ticket.
A support bundle is one JSON file that describes your self-hosted server. You send it when you ask for help. CodeHerder has no access to your install, so the bundle is the only way we see its state.
The bundle holds four parts: setting names, versions, health checks and counters. It holds no log lines and no session text. You produce it with one ch command. Read the file before you send it.
Fields
Each key is a dotted path into the bundle JSON.
Settings
| Key | Meaning |
|---|---|
settings.names |
The names of the registered CH_ server settings that are set on the server host, sorted alphabetically. A setting with a blank value counts as not set. Values are never included. |
Versions
| Key | Meaning |
|---|---|
version.version |
The server release version. |
version.productVersion |
The Core release tag the server wraps. Missing on an unstamped build. |
version.productCommit |
The full Core commit of that tag. Missing on an unstamped build. |
version.commit |
The commit the server was built from. Missing on an unstamped build. |
Health checks
| Key | Meaning |
|---|---|
health.status |
ok, db_unavailable, identity_unavailable or mail_unavailable. |
health.productVersion |
The Core release tag, as the health check reports it. Missing on an unstamped build. |
health.version |
The server version, as the health check reports it. |
health.db |
ok, writer_saturated or unavailable. |
health.atRestKeys |
The boot-time at-rest key check: ok, mismatch, unreadable_rows or not_checked. |
health.identity |
The sign-in token validator: off, ok, no_keys or init_failed. |
health.mail |
The mailer: ses, fake or init_failed. |
health.signupEnabled |
Whether the first-account bootstrap is still open. |
Counters
The db keys describe the latest database sample. db is null before the server takes its first sample. It is also null when no sample is newer than 30 days. That happens if you switch sampling off with CH_SERVER_METRICS_SEC=0. By default the server samples every 5 minutes.
The traceExport keys describe the server process that answered. They start again from zero when that process restarts. When trace export is not set up, traceExport.enabled is false and the other traceExport counters are zero.
| Key | Meaning |
|---|---|
db.collectedAt |
When the sample was taken. |
db.eventsCount |
Estimated rows in the events table (planner statistics, not an exact count; see db.eventsCountBasis). |
db.eventsCountBasis |
How db.eventsCount was obtained: estimated. |
db.costEventsCount |
Estimated rows in the cost events table (planner statistics, not an exact count; see db.costEventsCountBasis). |
db.costEventsCountBasis |
How db.costEventsCount was obtained: estimated. |
db.sandboxesCount |
Rows in the sandboxes table. |
db.tasksCount |
Rows in the tasks table. |
db.dbSizeBytes |
Database size in bytes. |
db.readerPool.inUse |
Reader pool connections in use. |
db.readerPool.maxOpen |
Reader pool size limit. |
db.readerPool.waitCount |
Reader pool waits since start. |
db.readerPool.deltaWaitMs |
Reader pool wait time since the last sample, in milliseconds. |
db.writerPool.inUse |
Writer pool connections in use. |
db.writerPool.maxOpen |
Writer pool size limit. |
db.writerPool.waitCount |
Writer pool waits since start. |
db.writerPool.deltaWaitMs |
Writer pool wait time since the last sample, in milliseconds. |
db.analyticsPool.inUse |
Analytics pool connections in use. |
db.analyticsPool.maxOpen |
Analytics pool size limit. |
db.analyticsPool.waitCount |
Analytics pool waits since start. |
db.analyticsPool.deltaWaitMs |
Analytics pool wait time since the last sample, in milliseconds. |
traceExport.enabled |
Whether trace export is on. |
traceExport.mappingVersion |
The version of the trace attribute mapping. |
traceExport.cursorLagSeconds |
How far the export trails new events, in seconds. |
traceExport.spansEmitted |
Spans exported. |
traceExport.pairsSkipped |
Event pairs skipped. |
traceExport.exportFailures |
Failed export attempts. |
traceExport.lastSweepAt |
When the export last ran. |
What the bundle never holds
- Bearer tokens and API keys.
- Provider credentials: AI keys, AWS keys and git tokens.
- The values of any setting.
- Log lines.
- Session text, and task or message content.
- SQL text. The slow-query report is not part of the bundle, because its fingerprints are SQL text.
Produce the bundle
Only an instance operator can produce the bundle. Sign in as a person whose verified email address is in CH_INSTANCE_OPERATORS on the server. The server refuses agent credentials and task or dev session credentials. A hosted deployment has no operator area, so the command is not available there. See Self-hosted operator access to add an address.
Run this command:
ch instance support-bundle > support-bundle.json
Open support-bundle.json. Check that it holds only the fields above.
Add --json to print the API response instead. It wraps the bundle in a data key. Either file is fine to send.
The bundle needs your database. If the command fails, send the error text you see. Say in your ticket that no bundle came out.
If you cannot run ch, you can call the route yourself. Use an operator’s API key in CH_TOKEN:
curl -H "Authorization: Bearer $CH_TOKEN" https://api.codeherder.com/v1/instance/support-bundle -o support-bundle.json
The response wraps the bundle in a data key. Send the whole file.
Send the bundle
- Email
support-bundle.jsonto your CodeHerder support contact. - Or attach it to a ticket in your own ticket system.
Do not paste the bundle into chat. Do not add logs to it.
Related guides
- Self-hosted deployment — run and upgrade a self-hosted server
- Self-hosted checks — test sign-in, mail, secrets, devices and updates with
ch instance check - Self-hosted operator access — add an instance operator
- Self-hosted logs — where the logs are, and how to ship them to storage you control
Last updated