<!-- source: https://deepwiki.com/qhkm/zeptoclaw/13.5-diagnostics-and-debugging -->

# Diagnostics and Debugging

- Dockerfile
- benches/message_bus.rs
- docs/BENCHMARK_RESULTS.md
- docs/PERFORMANCE.md
- src/bin/benchmark.rs
- src/cli/daemon.rs
- src/cli/doctor.rs
- src/health.rs

This page covers ZeptoClaw's diagnostic utilities, health monitoring systems, and debugging techniques for troubleshooting configuration issues, runtime errors, and performance problems.

## Overview

ZeptoClaw provides several diagnostic tools for validating system health:

Sources: [src/cli/doctor.rs33-49](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/doctor.rs#L33-L49) [src/health.rs1-12](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/health.rs#L1-L12) [src/bin/benchmark.rs1-11](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/bin/benchmark.rs#L1-L11) [src/cli/daemon.rs1-10](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/daemon.rs#L1-L10)

## The Doctor Command

The `doctor` command runs a suite of diagnostic checks and reports issues by category and severity.

### Command Usage

```

```

### Diagnostic Flow

The `run_diagnostics` function coordinates multiple sub-checks, collecting `DiagItem` results into a report.

```

```

Sources: [src/cli/doctor.rs33-49](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/doctor.rs#L33-L49)

### Diagnostic Categories

#### Configuration and Workspace

- Config Validation : check_config warns if LLM parameters like temperature are outside the typical 0.0-2.0 range src/cli/doctor.rs 51-66
- Permissions : check_workspace_writable attempts to write a .zeptoclaw_doctor_probe file to verify the filesystem is writable src/cli/doctor.rs 68-99

#### Environment and Binaries

ZeptoClaw probes for required system binaries by executing them with `--version`. It specifically checks for `sh` (required for `ShellTool`) and `git` (required for skill installation and the git tool) [src/cli/doctor.rs101-140](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/doctor.rs#L101-L140)

#### Provider and Channel Connectivity

- Provider Config : check_providers ensures at least one API key is present for Anthropic, OpenAI, OpenRouter, or Groq src/cli/doctor.rs 142-172
- Channel Config : check_channels validates that enabled channels (Telegram, Discord) have non-empty tokens src/cli/doctor.rs 174-222

## Runtime Health and Metrics

When running in gateway or daemon mode, ZeptoClaw tracks internal health via the `HealthRegistry` and `UsageMetrics`.

### Health Registry and Endpoints

The `HealthRegistry` maintains the status of named components (e.g., "telegram", "provider"). It drives the `/health` (liveness) and `/ready` (readiness) endpoints [src/health.rs187-209](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/health.rs#L187-L209)

### Memory and Resource Monitoring

ZeptoClaw includes a platform-specific Resident Set Size (RSS) helper `get_rss_bytes` to monitor memory usage without external dependencies [src/health.rs44-128](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/health.rs#L44-L128)

- macOS : Uses mach_task_self() and task_info() src/health.rs 45-102
- Linux : Reads and parses /proc/self/statm src/health.rs 104-122

## Performance Benchmarking

ZeptoClaw includes a dedicated load-testing utility to measure system behavior under stress.

### Benchmark Utility

The `benchmark` binary simulates concurrent users and collects metrics on latency, throughput, and error rates [src/bin/benchmark.rs55-62](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/bin/benchmark.rs#L55-L62)

```

```

Sources: [src/bin/benchmark.rs30-53](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/bin/benchmark.rs#L30-L53) [src/bin/benchmark.rs111-140](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/bin/benchmark.rs#L111-L140) [src/bin/benchmark.rs242-259](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/bin/benchmark.rs#L242-L259)

### Key Performance Findings

- Memory Efficiency : ZeptoClaw uses approximately 12 KB of RAM per concurrent user docs/PERFORMANCE.md 9
- Scalability : Handles 1000+ concurrent users on a 512MB RAM VPS docs/BENCHMARK_RESULTS.md 198-204
- Latency : Average latency remains <1ms for message routing docs/BENCHMARK_RESULTS.md 100-103

## Daemon and Supervision

The `zeptoclaw daemon` command provides a supervisor that manages the gateway process with automatic restarts.

### Daemon State Tracking

The supervisor writes its state to `~/.zeptoclaw/daemon_state.json` via `write_state` [src/cli/daemon.rs42-50](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/daemon.rs#L42-L50)

- Started At : ISO timestamp of daemon start src/cli/daemon.rs 28
- Restart Count : Number of times the gateway has crashed src/cli/daemon.rs 37
- Component State : Tracks individual component status like "gateway" src/cli/daemon.rs 34-39

### Backoff Strategy

The `cmd_daemon` loop implements an exponential backoff for restarts using `compute_backoff` [src/cli/daemon.rs17-19](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/daemon.rs#L17-L19)

- Initial Backoff : 1,000ms src/cli/daemon.rs 14
- Maximum Backoff : 300,000ms (5 minutes) src/cli/daemon.rs 15

Sources: [src/cli/daemon.rs87-133](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/daemon.rs#L87-L133)

## Debugging Tools Summary

Sources: [src/cli/doctor.rs33-49](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/doctor.rs#L33-L49) [src/health.rs187-209](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/health.rs#L187-L209) [src/bin/benchmark.rs55-108](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/bin/benchmark.rs#L55-L108) [src/cli/daemon.rs26-31](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/daemon.rs#L26-L31) [Dockerfile65](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Dockerfile#L65-L65)
