diff --git a/README.md b/README.md index b81b0f8aa9..8a4fdc886b 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Manage and run tasks in parallel. Orchestrate agents. Review changes. Ship value. -[Features](docs/features.md) | [Workflows](docs/workflow-tips.md) | [Run as a Service](docs/run-as-a-service.md) | [Roadmap](docs/roadmap.md) | [Contributing](CONTRIBUTING.md) | [Architecture](docs/ARCHITECTURE.md) | [Discord](https://discord.gg/gWdCPGcFCD) +[Features](docs/features.md) | [Workflows](docs/workflow-tips.md) | [Run as a Service](docs/run-as-a-service.md) | [Debug Logs](docs/debug-logs.md) | [Roadmap](docs/roadmap.md) | [Contributing](CONTRIBUTING.md) | [Architecture](docs/ARCHITECTURE.md) | [Discord](https://discord.gg/gWdCPGcFCD)

Kandev Demo diff --git a/docs/debug-logs.md b/docs/debug-logs.md new file mode 100644 index 0000000000..eb020b3cfd --- /dev/null +++ b/docs/debug-logs.md @@ -0,0 +1,209 @@ +# Collect Debug Logs + +Use this guide when a maintainer asks for frontend or backend logs while investigating a Kandev issue. + +Debug logs can include prompts, tool calls, file paths, task IDs, repository names, and snippets of local context. Review the files before sharing them publicly. Prefer sending them in a private support thread when they may contain sensitive data. + +## Which Logs to Send + +A maintainer may ask for one kind of log or for both: + +- **Frontend logs**: Browser console output from the affected page. These are usually enough for UI issues, layout problems, stale page state, missing updates, or click flows that behave incorrectly. +- **Backend logs**: Terminal or service logs from the Kandev server. These are useful for startup failures, agent failures, task execution problems, integration errors, database errors, and service issues. +- **Both**: Best when the issue crosses the UI and server boundary, such as WebSocket updates, task/session state mismatches, missing messages, or anything that is hard to classify. + +If the maintainer asks for frontend logs only, you do not need to send `~/kandev-debug.log` unless they ask for it later. + +## Quick Steps + +Use these steps for a normal Homebrew, npm, or npx install. If you run Kandev as a service or container, use the matching section below so the logs come from the same data directory, port, and deployment that has the issue. + +1. Stop the Kandev server you are already using. + - If it is running in a terminal, press `Ctrl-C`. + - If it is running as a user service, run `kandev service stop`. + - If it is running as a system service, run `sudo kandev service stop --system`. +2. Start Kandev in debug mode using the same install channel: + + ```bash + # Homebrew or global npm install + kandev --debug 2>&1 | tee ~/kandev-debug.log + ``` + + ```bash + # npx install + npx -y kandev@latest --debug 2>&1 | tee ~/kandev-debug.log + ``` + +3. Open the task or page that has the issue. +4. Open the browser DevTools Console, clear it, enable verbose/debug messages, then refresh the page. +5. Reproduce the issue. +6. Share: + - The browser console export or screenshot/text, if frontend logs were requested. + - `~/kandev-debug.log`, if backend logs were requested. + - The task URL or task ID, and a short description of what you clicked before the issue happened. +7. When done, press `Ctrl-C` in the debug terminal. If you stopped a service, start it again: + + ```bash + kandev service start + ``` + + ```bash + sudo kandev service start --system + ``` + +## Frontend Console Logs + +The frontend debug logs are browser console logs. They are most useful when they only contain the page and task that has the issue. + +1. Start Kandev with `--debug`. +2. Open the affected task details page. +3. Open DevTools. + - Chrome or Edge: right-click the page, choose **Inspect**, then open **Console**. + - Firefox: right-click the page, choose **Inspect**, then open **Console**. +4. In the Console: + - Clear existing logs. + - Enable **Verbose** or **Debug** logs. Kandev frontend debug lines use `console.debug`. + - Enable **Preserve log** if the issue involves page reloads or navigation. + - Leave the filter box empty unless a maintainer asks for a specific filter. +5. Refresh the page. +6. Reproduce the issue. +7. Copy or export the Console output and share it with the maintainer. + +You can check whether frontend debug mode is active by typing this in the Console: + +```js +window.__KANDEV_DEBUG +``` + +It should print `true`. + +## Backend Logs + +When Kandev is started with: + +```bash +kandev --debug 2>&1 | tee ~/kandev-debug.log +``` + +the backend logs are written to the terminal and saved to `~/kandev-debug.log`. + +Leave that terminal open while reproducing the issue. After the issue happens, send the saved file. + +## Service Installs + +If you normally run Kandev as a service, the cleanest debug flow is usually: + +```bash +kandev service stop +kandev --debug 2>&1 | tee ~/kandev-debug.log +# reproduce the issue +# press Ctrl-C +kandev service start +``` + +For a system service: + +```bash +sudo kandev service stop --system +sudo KANDEV_HOME_DIR=/var/lib/kandev kandev --debug 2>&1 | tee ~/kandev-debug.log +# reproduce the issue +# press Ctrl-C +sudo kandev service start --system +``` + +If the service was installed with a custom home directory or port, first run: + +```bash +kandev service config +``` + +For a system service: + +```bash +sudo kandev service config --system +``` + +Then start debug mode with the same values shown in the service config: + +```bash +KANDEV_HOME_DIR=/path/from/service/config kandev --debug --port 2>&1 | tee ~/kandev-debug.log +``` + +For a custom system service, run the same command with `sudo`. + +If you should not stop the service, collect the existing service logs instead: + +```bash +kandev service logs > ~/kandev-service.log +``` + +```bash +sudo kandev service logs --system > ~/kandev-service.log +``` + +To capture live logs while reproducing: + +```bash +kandev service logs -f | tee ~/kandev-service.log +``` + +```bash +sudo kandev service logs -f --system | tee ~/kandev-service.log +``` + +## Container Installs + +For Docker or Kubernetes installs, collect logs from the running container or pod. Do not start `kandev --debug` on the host unless a maintainer asks you to, because that starts a separate local instance. + +For Docker: + +```bash +docker logs kandev > ~/kandev-container.log +docker logs -f kandev | tee ~/kandev-container-live.log +``` + +If you need to recreate the container with debug logging, keep the same image, published port, and `/data` volume, then add `KANDEV_LOG_LEVEL=debug`: + +```bash +docker stop kandev +docker rm kandev +docker run -p 38429:38429 \ + -v kandev-data:/data \ + -e KANDEV_LOG_LEVEL=debug \ + --name kandev \ + ghcr.io/kdlbs/kandev:latest +``` + +For Kubernetes: + +```bash +kubectl logs deploy/kandev > ~/kandev-container.log +kubectl logs -f deploy/kandev | tee ~/kandev-container-live.log +``` + +If the maintainer asks for debug-level Kubernetes logs, set `KANDEV_LOG_LEVEL=debug` on the existing workload and keep the same volume claim and service port. + +## Improve Kandev Log Bundle + +Kandev also has a built-in path for sharing recent logs with a task: + +1. Start Kandev with `--debug`. +2. Reproduce the issue in the same browser tab. +3. Open **Improve Kandev** from the sidebar. +4. Leave **Include recent backend & browser logs as context for the agent** checked. +5. Submit the issue. + +This writes recent backend logs and browser console events to a temporary bundle and adds the bundle file paths to the task description. + +## What to Send + +When reporting an issue, include: + +- Kandev version: `kandev --version` or the version shown in Settings. +- Install method: Homebrew, npx, npm global, service, Docker, or source checkout. +- Operating system. +- The task URL or task ID. +- The requested logs: frontend console logs, backend logs, or both. +- The exact steps that reproduce the issue. + +Do not send your SQLite database, repository contents, credentials, API keys, or screenshots containing secrets unless a maintainer explicitly asks for them and you are comfortable sharing them privately.