LogMaster/docs/VIEWER.md

📋 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

cp .env.viewer .env
node dist-server/server.js

Option 2: Inline Environment Variables

LOG_MODE=viewer PORT=9090 LOG_SOURCES=/var/log/syslog,/app/logs/*.log node dist-server/server.js

Option 3: Docker

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)

{
  "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

LOG_MODE=viewer
PORT=9090
LOG_SOURCES=/var/log/syslog

Multiple sources with glob

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

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

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)

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

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: