Skip to content
ChannelWatch

Debug Bundles

When something goes wrong and you need help, a debug bundle gives you a single zip file with the information needed to diagnose the problem. Everything sensitive is redacted before the file is written.

Generating a bundle

Section titled “Generating a bundle”

From the CLI

Section titled “From the CLI”
Terminal window
docker exec channelwatch channelwatch doctor debug bundle

This produces a file named channelwatch-debug-<timestamp>.zip in the current working directory inside the container. Copy it out with:

Terminal window
docker cp channelwatch:/channelwatch-debug-2026-04-19T14-32-01.zip ./channelwatch-debug.zip

From the web UI

Section titled “From the web UI”

Go to Settings > Advanced > Generate debug bundle. The browser downloads the zip file directly. The contents are identical to the CLI output.

What the bundle contains

Section titled “What the bundle contains”
FileContents
manifest.jsonChannelWatch version, architecture, DVR count (no DVR identifiers)
settings_sanitized.jsonAll settings with host, port, API key, webhook URL, and notification URL values stripped
logs/app.logLast 500 lines of the application log, with IP addresses, hostnames, and tokens regex-redacted
health_snapshot.jsonDVR count and aggregate health state only

What is NOT included

Section titled “What is NOT included”

The following are explicitly excluded:

  • encryption.key (your credential encryption key)
  • channelwatch.db (the SQLite activity database)
  • Raw DVR API keys, webhook tokens, or notification provider credentials
  • Full IP addresses or hostnames in log lines (replaced with [REDACTED])

The sanitization is applied by the bundle generator, not by a post-processing step. The redacted values never appear in the zip.

Inspecting before sharing

Section titled “Inspecting before sharing”

Before attaching a bundle to a GitHub issue, unzip it and review the contents:

Terminal window
unzip -l channelwatch-debug.zip
unzip channelwatch-debug.zip -d bundle-review/
cat bundle-review/settings_sanitized.json

Confirm that settings_sanitized.json shows "[REDACTED]" for any field that contained a credential or network address.

Zero phone-home policy

Section titled “Zero phone-home policy”

ChannelWatch does not send telemetry, crash reports, or usage data to any server. There is no default analytics infrastructure. The debug bundle is a local file that goes nowhere unless you choose to share it.

This is an architectural guarantee, not just a policy. There is no background process, no scheduled upload, and no opt-out toggle because there is nothing to opt out of.

Optional user-supplied crash DSN

Section titled “Optional user-supplied crash DSN”

If you want automatic crash reporting for your own instance, you can configure a Sentry or GlitchTip DSN in Settings > Advanced > Crash Reporting DSN. When set, unhandled exceptions are routed to your DSN. No data goes to any ChannelWatch-operated infrastructure.

Attaching to a GitHub issue

Section titled “Attaching to a GitHub issue”

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

  1. Generate the bundle using the CLI or web UI.
  2. Inspect the contents to confirm no credentials are present.
  3. Attach the zip file to the issue, or paste the relevant section of logs/app.log directly.

The manifest.json version field helps maintainers identify which release you are running without asking.

Section titled “Related pages”