# Usage Guide

This guide covers all features of the Tyto dashboard.

## Dashboard Overview

The main dashboard displays real-time system metrics in a card-based layout. Each card can be expanded for more details.

### Navigation

| Element | Description |
|---------|-------------|
| **Header** | Host selector, refresh rate, theme toggle, user menu |
| **Cards** | Metric categories (CPU, Memory, Disk, etc.) |
| **Sparklines** | Historical trends for key metrics |

### Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `T` | Toggle dark/light theme |
| `R` | Cycle refresh rate (1s → 5s → 10s → 30s) |
| `?` | Show keyboard shortcuts help |
| `Esc` | Close modals and panels |

## Metric Cards

### System Information

Displays basic system information:
- **Hostname**: System hostname
- **Kernel**: Linux kernel version
- **Uptime**: Time since last boot
- **Architecture**: CPU architecture (x86_64, arm64, etc.)

### CPU

Shows processor utilization:
- **Total Usage**: Overall CPU usage percentage
- **Per-Core**: Individual core utilization bars
- **Load Average**: 1, 5, and 15-minute load averages
- **Frequency**: Current and max CPU frequency

**Sparkline**: Shows CPU usage trend over the last hour.

### Memory

Displays RAM and swap usage:
- **Used / Total**: Current memory consumption
- **Buffers**: Kernel buffer cache
- **Cached**: Page cache
- **Available**: Memory available for applications
- **Swap**: Swap usage if enabled

**Sparkline**: Shows memory usage trend.

### Disk

Shows storage information:
- **Mount Points**: Each mounted filesystem
- **Usage Bar**: Visual usage indicator
- **Size**: Used and total space
- **I/O Rates**: Read/write speeds (MB/s)

**Sparkline**: Shows disk I/O trend.

### Network

Displays network interface statistics:
- **Interfaces**: Each network interface (eth0, wlan0, etc.)
- **IP Address**: IPv4 and IPv6 addresses
- **Bandwidth**: Current upload/download rates
- **Total Traffic**: Cumulative bytes transferred
- **Connections**: Active TCP connection count

**Sparkline**: Shows bandwidth trend.

### Processes

Lists top processes by resource usage:
- **By CPU**: Processes consuming most CPU
- **By Memory**: Processes using most RAM
- **Total Count**: Number of running processes

Click a process to see details:
- Full command line
- User and group
- State and priority
- Open files and threads

**Process Control:**
- **Terminate (SIGTERM)**: Graceful shutdown
- **Kill (SIGKILL)**: Force kill
- **Pause (SIGSTOP)**: Suspend process
- **Resume (SIGCONT)**: Continue paused process

### Temperature

Shows hardware sensor readings:
- **CPU Temperature**: Core temperatures
- **GPU Temperature**: Graphics card (if available)
- **Disk Temperature**: NVMe/SATA sensors
- **Other Sensors**: Motherboard, ambient, etc.

### GPU

Displays graphics card metrics (if detected):
- **Utilization**: GPU compute usage
- **VRAM**: Video memory usage
- **Temperature**: GPU temperature
- **Power**: Current power consumption
- **Clocks**: Core and memory frequencies

Supports: NVIDIA, AMD, and Intel GPUs.

### Docker

Lists running containers (requires Docker socket mount):
- **Container Name**: Container identifier
- **Image**: Base image
- **Status**: Running, paused, stopped
- **CPU/Memory**: Resource usage per container

### Systemd

Shows system service status (requires D-Bus socket mount):
- **Service Name**: Unit name
- **State**: Active, inactive, failed
- **Sub-state**: Running, exited, dead

## Alerts & Notifications

### Configuring Thresholds

1. Click the **Alerts** card header
2. Click **Configure Thresholds**
3. Set levels for each metric:

| Metric | Warning | Critical |
|--------|---------|----------|
| CPU | 80% | 95% |
| Memory | 85% | 95% |
| Disk | 80% | 90% |

4. Click **Save Configuration**

### Alert States

| State | Description |
|-------|-------------|
| **Normal** | Below warning threshold |
| **Warning** | Above warning, below critical |
| **Critical** | Above critical threshold |

### Desktop Notifications

1. Enable **Desktop Notifications** toggle in Alerts card
2. Allow browser notification permission when prompted
3. Notifications appear for new warning/critical alerts

**Behavior:**
- Warning alerts auto-dismiss after 10 seconds
- Critical alerts require manual acknowledgment
- Click notification to jump to affected metric

### Acknowledging Alerts

1. Click the alert in the Alerts card
2. Click **Acknowledge**
3. Alert moves to "Acknowledged" section

## Log Viewer

Access at `/logs` in the dashboard.

### Filtering Logs

| Filter | Description |
|--------|-------------|
| **Search** | Full-text search in messages |
| **Level** | Filter by severity (debug, info, warning, error, fatal) |
| **Source** | Filter by source type (journal, file, docker) |
| **Agent** | Filter by agent ID (multi-device mode) |

### Live Mode

Click **Go Live** to stream logs in real-time. New entries appear at the top.

### Log Sources

| Source | Description |
|--------|-------------|
| **Systemd Journal** | System and service logs |
| **File** | Tailed log files |
| **Docker** | Container stdout/stderr |

## Data Export

### Exporting Metrics

1. Click the **Export** button in the header
2. Choose format:
   - **CSV**: Spreadsheet-compatible
   - **JSON**: Machine-readable
3. File downloads with current timestamp

### API Export

```bash
# CSV export
curl http://localhost:8080/api/v1/export/metrics?format=csv -o metrics.csv

# JSON export
curl http://localhost:8080/api/v1/export/metrics?format=json -o metrics.json
```

## Theme & Display

### Dark/Light Mode

Toggle with:
- `T` keyboard shortcut
- Theme toggle button in header

Theme preference is saved in browser localStorage.

### Responsive Design

The dashboard adapts to screen size:
- **Desktop**: Full card grid
- **Tablet**: Reduced columns
- **Mobile**: Single column, simplified charts

## Multi-Host Switching

In standalone mode with multiple hosts configured:

1. Click the **host selector** dropdown in the header
2. Select a host or click **Add Remote Host**
3. Enter host name and URL
4. Dashboard switches to selected host

Host configurations are stored in browser localStorage.

## Performance Tips

### Reduce Bandwidth

- Increase refresh rate (R key) to 10s or 30s
- Disable sparkline history if not needed

### Reduce Server Load

- Limit visible cards
- Use longer refresh intervals
- Disable log streaming when not needed

### Browser Performance

- Close unused tabs
- Disable desktop notifications if not needed
- Use production builds (not development mode)