CodeHerderSearch⌘KRequest access →

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.json to 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.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close