Debug Bundles

ChannelWatch ships a source-backed debug-bundle generator through channelwatch doctor debug bundle. The backend also exposes a bundle download endpoint at /api/v1/debug/bundle for admin-authorized access. Both paths produce the same local, operator-controlled archive for troubleshooting.

Note

The shipped feature is source-backed at the CLI and backend API layers. This page does not claim a separate web-UI button unless you verify one in the current app surface.

The doctor CLI page and this page describe the same shipped bundle workflow: the CLI command is available today, and the backend endpoint exposes the same sanitized archive for authenticated support use.

What is available today

Use these support surfaces in the current release:

Tool	What it gives you	Where to learn more
channelwatch doctor debug bundle	A sanitized zip with bundle metadata, sanitized settings, a redacted log tail, and a minimal health snapshot	doctor CLI
GET /api/v1/debug/bundle	The same sanitized bundle as an authenticated backend download	REST API
Diagnostics tab	Connectivity tests, API checks, alert tests, and in-app troubleshooting	Diagnostics
CLI diagnostic flags	Headless versions of the same tests for automation or SSH-only systems	CLI Commands
Container logs	The most detailed view of connection events, alert sends, and errors	docker logs channelwatch

Generate a bundle

Run the command inside the container:

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:

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:

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

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.

Today health_snapshot.json is intentionally minimal. The current generator records only the enabled DVR count rather than a full per-DVR health report.

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 the Diagnostics tab.
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:

docker logs channelwatch
docker logs -f channelwatch

4. For a DVR-specific problem, include the current response from /api/v1/dvrs/{dvr_id}/health.
5. For a general service problem, include the current response from /api/health.

Sharing safely

The bundle generator sanitizes sensitive fields before writing the archive. Current source-backed 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

Note

Review the archive before sharing anyway. Sanitization is source-backed, but you still know your environment best and may want to trim unrelated logs or metadata.

Zero phone-home policy

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.

Attaching 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 ChannelWatch version shown in the UI or container image tag if you know it.

Related pages

• doctor CLI - command reference for debug bundle
• Diagnostics - web UI troubleshooting tools available today
• CLI Commands - current diagnostic flags for headless environments
• Per-DVR Health - real-time health endpoint
• Health & Readiness Probes - probe endpoints and watchdog behavior
• Common Issues - solutions to frequent problems before filing a bug