# Self-hosted support bundle

Source: https://codeherder.com/docs/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, as a list. 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.

| Key | Meaning |
| --- | --- |
| `db.collectedAt` | When the sample was taken. |
| `db.eventsCount` | Rows in the events table. |
| `db.costEventsCount` | Rows in the cost events table. |
| `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

You need an instance operator login for `ch`. Run this command:

```
ch instance support-bundle > support-bundle.json
```

Open `support-bundle.json`. Check that it holds only the fields above.

If you cannot run `ch`, you can call the route yourself. Use an instance operator token in `CH_TOKEN`:

```
curl -H "Authorization: Bearer $CH_TOKEN" {{api_base}}/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.

## Related guides

- [Self-hosted deployment](https://codeherder.com/docs/self-hosting/) — run and upgrade a self-hosted server
- [Self-hosted logs](https://codeherder.com/docs/self-host-logs/) — where the logs are, and how to ship them to storage you control