Skip to content

debug-logs.md

Latest commit

 

History

History
209 lines (149 loc) · 6.97 KB

debug-logs.md

File metadata and controls

209 lines (149 loc) · 6.97 KB
Raw

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:

    # Homebrew or global npm install
kandev --debug 2>&1 | tee ~/kandev-debug.log
    # 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:

    kandev service start
    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:

window.__KANDEV_DEBUG

It should print true.

Backend Logs

When Kandev is started with:

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:

kandev service stop
kandev --debug 2>&1 | tee ~/kandev-debug.log
# reproduce the issue
# press Ctrl-C
kandev service start

For a system service:

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:

kandev service config

For a system service:

sudo kandev service config --system

Then start debug mode with the same values shown in the service config:

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:

kandev service logs > ~/kandev-service.log
sudo kandev service logs --system > ~/kandev-service.log

To capture live logs while reproducing:

kandev service logs -f | tee ~/kandev-service.log
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:

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:

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:

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.