# 📋 Log Viewer — User Guide

## Overview

The Log Viewer is a web-based interface for reading, filtering, searching, and exporting log files from multiple sources including local files, S3 buckets, and remote collector streams.

---

## Starting the Viewer

### Option 1: Environment File
```bash
cp .env.viewer .env
node dist-server/server.js
```

### Option 2: Inline Environment Variables
```bash
LOG_MODE=viewer PORT=9090 LOG_SOURCES=/var/log/syslog,/app/logs/*.log node dist-server/server.js
```

### Option 3: Docker
```bash
docker run -d -p 9090:8080 \
  -e LOG_MODE=viewer \
  -e LOG_SOURCES=/logs/*.log \
  -v /var/log:/logs:ro \
  logviewer
```

### Option 4: Config File (`logviewer.config.json`)
```json
{
  "mode": "viewer",
  "port": 9090,
  "viewer": {
    "sources": ["/var/log/syslog", "/app/logs/*.log"],
    "theme": "dark",
    "refreshInterval": 2000,
    "tailMode": true,
    "maxLines": 50000
  },
  "remoteCollector": {
    "url": "http://collector-server:8081"
  }
}
```

---

## GUI Guide

### Layout

```
┌─────────────────────────────────────────────────────────────┐
│  [📂 File] [☁️ S3] [🔄 Reload] | [Search...] | [Levels ▼] │  ← Toolbar
├──────────┬──────────────────────────────────────────────────┤
│          │                                                  │
│  Sources │              Log Output                          │
│  Sidebar │                                                  │
│          │  Each line shows:                                │
│  📁 Files│  [LineNo] [Source] [Timestamp] [LEVEL] Content   │
│  ☁️ S3   │                                                  │
│  📡 Local│  New lines flash blue briefly                    │
│  🌐 Remote                                                  │
│          │                                                  │
├──────────┴──────────────────────────────────────────────────┤
│  Status: Ready · 1247 lines · 1247 shown        TAIL WRAP  │  ← Status Bar
└─────────────────────────────────────────────────────────────┘
```

### Toolbar Actions

| Button | Action |
|--------|--------|
| 📂 File | Add a local file path (supports globs like `/var/log/*.log`) |
| ☁️ S3 | Add an S3 bucket source (access key, secret, region, bucket, prefix) |
| 🔄 Reload | Refresh all sources |
| ⬇️ Tail | Toggle auto-scroll to new lines |
| ↩️ Wrap | Toggle word wrap for long lines |
| 🕐 Time | Show/hide timestamp column |
| Search box | Type to filter. Click `.*` for regex, `Aa` for case-sensitive |
| Level dropdown | Filter by log level (ERROR, WARN, INFO, etc.) |
| Source dropdown | Filter by specific source file |
| 💾 Export | Download visible logs as TXT or JSON |
| 🌙/☀️ | Toggle dark/light theme |

### Sidebar

The sidebar shows all configured sources grouped by type:
- **📁 Files** — Local log files
- **☁️ S3** — S3 bucket sources
- **📡 Collector Streams** — Local collector streams (if mode=both)
- **🌐 Remote Streams** — Streams from a remote collector

Click a source to view only its logs. Click again or select "All Sources" to see everything.

### Live Highlighting

When tail mode is active, new log lines that appear during auto-refresh are briefly highlighted with a blue left border and background fade. This makes it easy to spot new entries in a busy log.

### Context Menu (Right-Click)

Right-click any log line for:
- 📋 Copy Line
- 🔖 Toggle Bookmark
- 🔍 Filter by this level
- 📋 Copy all visible lines

### Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `Ctrl+F` | Focus search box |
| `Ctrl+Shift+F` | Enable regex mode + focus search |
| `Ctrl+T` | Toggle tail mode |
| `Ctrl+W` | Toggle word wrap |
| `Ctrl+G` | Go to line number |
| `Ctrl+Shift+T` | Toggle theme |
| `Ctrl+=` / `Ctrl+-` | Zoom in/out |
| `Ctrl+0` | Reset zoom |
| `Home` / `End` | Scroll to top/bottom |
| `Escape` | Clear search / close modals |

---

## Configuration Reference

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `LOG_MODE` | `both` | Set to `viewer` for viewer-only mode |
| `PORT` | `8080` | HTTP port |
| `LOG_SOURCES` | — | Comma-separated file paths or globs |
| `LOG_THEME` | `dark` | `dark` or `light` |
| `LOG_REFRESH_INTERVAL` | `2000` | Auto-refresh interval in ms |
| `LOG_TAIL_MODE` | `true` | Start with tail mode enabled |
| `LOG_MAX_LINES` | `50000` | Max lines loaded per file |
| `LOG_DEFAULT_LEVEL` | `ALL` | Default level filter |
| `REMOTE_COLLECTOR_URL` | — | URL of a remote collector to read streams from |
| `S3_ACCESS_KEY_ID` | — | Global S3 access key |
| `S3_SECRET_ACCESS_KEY` | — | Global S3 secret key |
| `S3_REGION` | `us-east-1` | Global S3 region |
| `S3_ENDPOINT` | — | Custom endpoint for S3-compatible services |
| `S3_SOURCE_<NAME>` | — | S3 source in format `bucket:prefix` |

### Supported File Formats

| Format | Extensions | How it works |
|--------|-----------|--------------|
| Plain text | `.log`, `.txt`, no extension | Direct read |
| Gzip | `.gz` | Decompressed with Node.js zlib |
| Bzip2 | `.bz2` | Decompressed via `bzcat` CLI |
| XZ | `.xz` | Decompressed via `xzcat` CLI |
| Zstandard | `.zst` | Decompressed via `zstdcat` CLI |

---

## Example Configurations

### Basic: View local syslog
```env
LOG_MODE=viewer
PORT=9090
LOG_SOURCES=/var/log/syslog
```

### Multiple sources with glob
```env
LOG_MODE=viewer
PORT=9090
LOG_SOURCES=/var/log/syslog,/var/log/auth.log,/app/logs/*.log,/app/logs/archived/*.gz
```

### Viewer connected to remote collector
```env
LOG_MODE=viewer
PORT=9090
REMOTE_COLLECTOR_URL=http://10.0.1.50:8081
LOG_SOURCES=/var/log/local-app.log
```

### Viewer with S3 sources
```env
LOG_MODE=viewer
PORT=9090
S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
S3_REGION=eu-central-1
S3_SOURCE_PROD=company-logs:production/app/
S3_SOURCE_INFRA=company-logs:infrastructure/
```

### Viewer with MinIO (S3-compatible)
```env
LOG_MODE=viewer
PORT=9090
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_REGION=us-east-1
S3_ENDPOINT=http://minio.local:9000
S3_SOURCE_LOGS=my-bucket:logs/
```

### Docker Compose: Viewer + Collector
```yaml
services:
  collector:
    image: logviewer
    ports: ["8081:8080", "5140:5140/udp"]
    environment:
      LOG_MODE: collector
      COLLECTOR_UDP_PORT: "5140"
    volumes:
      - collector-data:/app/collector-data

  viewer:
    image: logviewer
    ports: ["9090:8080"]
    environment:
      LOG_MODE: viewer
      REMOTE_COLLECTOR_URL: http://collector:8080
    depends_on: [collector]

volumes:
  collector-data:
```