> For the complete documentation index, see [llms.txt](https://docs.observal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.observal.io/cli-reference/doctor/support.md).

# Support bundles

Generate and inspect redacted diagnostic support bundles.

Both workflows support `--output table|json`. Bundle generation writes a `.tar.gz` archive as its intended side effect. JSON mode returns archive metadata and never prompts.

## Generate a bundle

```bash
observal doctor support bundle --output json
```

Choose the archive path with the hard-renamed `--file/-f` option:

```bash
observal doctor support bundle \
  --file /tmp/observal-support.tar.gz \
  --logs-since 2h \
  --no-include-system \
  --output json
```

The former archive-path meaning of `--output/-o` has been removed. `--output/-o` now consistently selects `table` or `json`.

### Options

| Option                                    | Purpose                                                               |
| ----------------------------------------- | --------------------------------------------------------------------- |
| `--file`, `-f`                            | Archive path; defaults to a timestamped file in the current directory |
| `--logs-since`                            | Positive duration up to 30 days, such as `30m`, `2h`, or `1d12h`      |
| `--include-system`, `--no-include-system` | Include or omit local system metrics                                  |
| `--force`, `--yes`                        | Overwrite an existing archive and accept the size warning             |
| `--output`, `-o`                          | Human or JSON result                                                  |

Existing archives prompt in human mode. JSON mode fails with a conflict unless `--force` or `--yes` is present.

JSON returns:

```json
{
  "path": "/tmp/observal-support.tar.gz",
  "size_bytes": 43120,
  "remote_status": "collected",
  "warnings": [],
  "collector_results": {},
  "redaction_counts": {}
}
```

## Collection behavior

Remote collectors use `POST /api/v1/support/collect` and require an administrator account. They provide:

* Application and migration versions
* PostgreSQL, ClickHouse, and Redis health
* Allowlisted configuration
* Aggregate table counts
* Error fingerprints
* Recent redacted log records

Local collectors provide allowlisted configuration processing and optional OS, CPU, memory, disk, and container-runtime details.

Remote collection is optional by design. Authentication, permission, version, network, or response failures are recorded in `remote_status` and `warnings`; local collection continues. This fallback is never silent.

Individual collector failures are retained in the manifest and JSON result. If no collector produces data, the command exits with code 9 and does not create an archive.

## Privacy and integrity

Support bundles contain aggregate diagnostics, not customer database rows or trace payloads.

Protections include:

* Configuration allowlisting before archive creation
* Redaction of passwords, tokens, API keys, private keys, authorization values, URL credentials, JWTs, AWS access keys, and high-entropy strings
* Redaction of collector error text before it enters the manifest
* Rejection of unknown collector names and unsafe archive paths
* Hashed host identity rather than a raw hostname
* SHA-256 inventory entries for every archived file
* Atomic archive replacement with mode `0600`

The manifest records collector status, redaction counts, file sizes, and hashes. Review every bundle before sharing it because logs and deployment metadata can still be operationally sensitive.

## Size budget

The uncompressed budget is 100 MB. Human mode asks before exceeding it. JSON mode requires `--force` and never prompts.

## Inspect a bundle

```bash
observal doctor support inspect ./observal-support.tar.gz --output json
```

Show one regular file:

```bash
observal doctor support inspect ./observal-support.tar.gz \
  --show health/postgres.json \
  --output json
```

JSON returns the manifest, safe regular-file inventory, schema warnings, and optional shown content:

```json
{
  "manifest": {"bundle_schema_version": "1"},
  "files": [{"path": "health/postgres.json", "size_bytes": 91}],
  "warnings": [],
  "shown": {"path": "health/postgres.json", "content": "{\"status\":\"ok\"}"}
}
```

Inspection never extracts files. It rejects traversal paths, links requested through `--show`, malformed or oversized manifests, and shown files larger than 1 MB. Unsafe archive members are omitted and reported as warnings.

## Exit codes

| Code | Meaning                                                                                                          |
| ---- | ---------------------------------------------------------------------------------------------------------------- |
| 5    | Bundle or requested member not found                                                                             |
| 6    | Destination archive already exists                                                                               |
| 7    | Invalid duration, unsafe archive, malformed manifest, oversized display, or missing non-interactive confirmation |
| 9    | No diagnostic data or archive write failure                                                                      |

## Related

* [`observal doctor`](/cli-reference/doctor.md): diagnose and repair telemetry instrumentation
* [`observal ops telemetry status`](/cli-reference/ops.md): check telemetry flow
* [Troubleshooting](/self-hosting/troubleshooting.md): deployment diagnosis


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.observal.io/cli-reference/doctor/support.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.