docs: add debug log collection guide (#1533)
This commit is contained in:
Carlos Florêncio
@@ -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)
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/screenshots/readme-intro.gif" alt="Kandev Demo">
|
||||
|
||||
@@ -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 <port from service config> 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.
|
||||
Reference in New Issue
Block a user