Skip to content
ChannelWatch

Debug Bundles

Generate a debug bundle when you need to share settings structure, a redacted log tail, and runtime details without exporting the raw database or encryption key. Download it from Diagnostics or create it through the doctor CLI. Neither action submits a support report.

Download from Diagnostics

Section titled “Download from Diagnostics”
  1. Open Diagnostics.
  2. Choose Download debug bundle. Secure-login installs require an administrator for this download.
  3. Save the ZIP, open it locally, and review the contents before sharing.
ChannelWatch v1.6.3 diagnostics showing Main DVR, seven passed tests, three disabled alerts marked Skipped, log tools and debug bundle download
Diagnostics debug bundleThe Balanced preset skips disabled alerts and shows the tested DVR without counting those alerts as failures. Captured from ChannelWatch v1.6.3 with safe demo data.View full-size screenshot

Generate from the CLI

Section titled “Generate from the CLI”

Run the command inside the container:

Terminal window
docker exec channelwatch channelwatch doctor debug bundle

By default the command writes channelwatch_debug_bundle.zip in the current working directory inside the container. To place it in the mounted config volume instead, set an explicit output path:

Terminal window
docker exec channelwatch channelwatch doctor debug bundle --output /config/channelwatch_debug_bundle.zip

If you want the archive on your workstation, copy it out after generation:

Terminal window
docker cp channelwatch:/config/channelwatch_debug_bundle.zip ./channelwatch_debug_bundle.zip

What the bundle contains

Section titled “What the bundle contains”

The current implementation writes four artifacts under a timestamped directory inside the zip:

  • manifest.json
  • settings_sanitized.json
  • logs/app.log
  • health_snapshot.json

That is intentionally narrower than a full data export. The raw SQLite database, the raw encryption key, and raw session-state files are excluded.

health_snapshot.json contains the enabled, non-deleted DVR count. It does not contact DVRs or include a full per-DVR health report. manifest.json records the app version, architecture, process runtime, and any verified runtime-generation claim. A CLI-generated bundle describes that CLI process; it does not prove which packages a separate web or core worker has loaded.

Collecting support information manually

Section titled “Collecting support information manually”

The bundle is usually enough for a first pass, but manual checks still help when you need live data or a narrower repro:

  1. Run the relevant checks in Diagnostics, using the CLI fallback if the v1.6.5 UI reports Unknown test name received.
  2. If the web UI is unavailable, run the matching CLI flags: --test-connectivity, --test-api, --test-alert, or --monitor-events.
  3. Capture recent container logs:
Terminal window
docker logs channelwatch
docker logs -f channelwatch
  1. For a DVR-specific problem, include the current response from /api/v1/dvrs/{dvr_id}/health.
  2. For a general service problem, include the current response from /api/health.

Raw health responses and container logs can contain DVR names, addresses, program titles, or device names. Redact them before posting publicly. Alert-test commands send real notifications.

Sharing safely

Section titled “Sharing safely”

The bundle generator sanitizes sensitive fields before writing the archive. Current behavior includes:

  • masking top-level app secrets such as the shared API key, Apprise credentials, and error-reporting DSNs
  • masking DVR host, port, and per-DVR api_key values in sanitized settings
  • masking webhook URLs and webhook secrets
  • redacting IPv4 addresses and URL hosts from the bundled log tail

Local generation and sharing

Section titled “Local generation and sharing”

The bundle command is still fully manual. ChannelWatch writes the zip locally and stops there. Nothing is uploaded unless you choose to copy or attach it.

For authenticated automation, GET /api/v1/debug/bundle downloads the same archive format and requires administrator access. See the REST API.

Attaching to a support report

Section titled “Attaching to a support report”

The easiest support path is Diagnostics > Report a Problem. It can create the public-safe report preview, attach screenshots, and validate one ChannelWatch debug bundle ZIP before the report is sent or packaged for manual upload.

The public issue body does not include screenshots, debug bundle contents, private email addresses, raw logs, API keys, webhook secrets, notification tokens, DVR API keys, or private config values.

Attaching manually to a GitHub issue

Section titled “Attaching manually to a GitHub issue”

When filing a bug report at github.com/CoderLuii/ChannelWatch/issues:

  1. Run the relevant checks in the Diagnostics tab or with the current CLI flags.
  2. Generate a debug bundle and inspect it before sharing.
  3. Attach the bundle, or paste the exact log window and health data into the issue if you prefer a smaller artifact.
  4. Include the app version and container image version separately. They can differ after an in-app update.
Section titled “Related pages”