observal doctor support

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

observal doctor support bundle --output json

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

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:

{
  "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

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

Show one regular file:

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:

{
  "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

observal doctor: diagnose and repair telemetry instrumentation
observal ops telemetry status: check telemetry flow
Troubleshooting: deployment diagnosis

Getting Started

Core Concepts

Use Cases

CLI Reference

Self-Hosting

Integrations

Reference

Security

Architecture Decisions

Contributing

observal doctor support

Generate a bundle

Options

Collection behavior

Privacy and integrity

Size budget

Inspect a bundle

Exit codes

​Generate a bundle

​Options

​Collection behavior

​Privacy and integrity

​Size budget

​Inspect a bundle

​Exit codes

​Related

Generate a bundle

Options

Collection behavior

Privacy and integrity

Size budget

Inspect a bundle

Exit codes

Related