logview-ag 0.8.0

A testable, responsive log viewer TUI with pluggable log source contexts

LogView

A testable, responsive log viewer TUI with pluggable log source contexts.

Features

• Multiple log sources: Local log files, syslog, Docker containers, GCP Cloud Logging, GKE, and more
• Format auto-detection: Automatically detects plain text, JSON Lines, and syslog formats
• Log discovery: Scan directories to find log files
• Tree-based context switcher: Organized view with configured sources at root, discovered logs in collapsible folder
• Flexible filtering: Time range, severity, text search, source filter, and source-specific fields
  • Server-side filtering: GCP/GKE adapters push source filters to Cloud Logging API (80-90% reduction in data transfer)
• Memory efficient: Batch processing and heap-based selection for large log files
• Application logging: Configurable rotating file handler for debugging
• Keyboard-first: Full functionality without mouse
• Testable: Interface-driven design with comprehensive test coverage

Installation

Quick Install (Recommended)

# Using pipx (isolated environment - recommended)
pipx install logview-ag

# Or using pip
pip install logview-ag

With Optional Dependencies

# Base installation (local logs only)
pip install logview-ag

# With GCP Cloud Logging support
pip install logview-ag[gcp]

# With GKE support
pip install logview-ag[gke]

# With Docker support
pip install logview-ag[docker]

# With context detection (auto-discover GCP/GKE)
pip install logview-ag[detection]

# With everything
pip install logview-ag[all]

From Source (Development)

git clone https://github.com/agileguy/logview.git
cd logview
pip install -e ".[all]"

System Requirements

• Python: 3.11 or higher
• Operating System: Linux or macOS
• Optional: pipx (recommended for isolated installation)

Checksum Verification

For security-conscious users, verify package integrity using checksums:

# After downloading the wheel from GitHub releases
# Download SHA256SUMS file
curl -fsSL https://github.com/agileguy/logview/releases/download/vX.Y.Z/SHA256SUMS -o SHA256SUMS

# Verify the checksum
sha256sum -c SHA256SUMS --ignore-missing

Expected output: logview_ag-X.Y.Z-py3-none-any.whl: OK

Uninstall

# Via the install script
curl -fsSL https://raw.githubusercontent.com/agileguy/logview/main/install.sh | bash -s -- --uninstall

# Or manually
pipx uninstall logview-ag  # if installed with pipx
pip uninstall logview-ag   # if installed with pip

# Remove configuration (optional)
rm -rf ~/.config/logview

Usage

# Run the TUI
logview

# Or as a module
python -m logview

Keyboard Shortcuts

Key	Action
↑/↓	Navigate log entries
Enter	View log details
c	Change context
d	Discover GCP/GKE contexts (requires [detection] extra)
f	Open filter (with preset support)
/	Search within results
n/N	Next/previous search match
e	Export visible logs to JSON/JSONL
s	Settings (theme, timestamp format)
?	Help
r	Refresh logs
Ctrl+T	Toggle dark/light mode
Ctrl+P	Command palette (change theme, run actions)
q	Quit

Configuration

Create ~/.config/logview/config.json:

{
  "contexts": [
    {
      "name": "app-logs",
      "type": "logfile",
      "path": "/var/log/myapp/app.log",
      "format": "auto"
    },
    {
      "name": "local-syslog",
      "type": "syslog",
      "path": "/var/log/syslog"
    },
    {
      "name": "docker-nginx",
      "type": "docker",
      "container": "nginx"
    },
    {
      "name": "gcp-logs",
      "type": "gcp",
      "project": "my-project",
      "log_name": "cloudaudit.googleapis.com%2Factivity"
    },
    {
      "name": "prod-gke",
      "type": "gke",
      "project": "my-project",
      "cluster": "prod-cluster"
    }
  ],
  "ui": {
    "theme": "dark",
    "timestamp_format": "%Y-%m-%d %H:%M:%S",
    "max_message_width": 80,
    "show_metadata": false
  }
}

See configs/example.json for a complete example.

Themes

LogView supports 12 built-in themes that can be changed via the settings modal (s key) or the command palette (Ctrl+P):

• Base themes: dark (default), light, ansi
• Custom themes: catppuccin-latte, catppuccin-mocha, dracula, flexoki, gruvbox, monokai, nord, solarized-light, tokyo-night

Theme changes persist automatically to your config file. You can also toggle between dark and light mode with Ctrl+T.

Settings Modal (s key):

• Theme selection (dropdown with all available themes)
• Timestamp format (common presets or custom format string)
• Max message width for wrapping
• Show/hide metadata in log list

All settings changes are saved immediately to your config file.

Application Logging

LogView logs its own activity to help with debugging. Configure logging in your config file:

{
  "logging": {
    "level": "DEBUG",
    "file": "~/.config/logview/logview.log",
    "max_size_mb": 10,
    "backup_count": 3
  }
}

Option	Default	Description
level	DEBUG	Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
file	~/.config/logview/logview.log	Log file path (null for default)
max_size_mb	10	Max log file size before rotation
backup_count	3	Number of rotated log files to keep

To view logs while running:

tail -f ~/.config/logview/logview.log

Docker Container Logs Setup

To view logs from Docker containers:

1. Install with Docker support:

   pipx install logview-ag[docker]  # or pip install logview-ag[docker]
   

2. Ensure Docker is running:

   docker info  # Should connect successfully
   

3. Add a Docker context to your config:

   {
     "name": "nginx-container",
     "type": "docker",
     "container": "nginx"
   }
   

Requirements:

• The docker Python package (installed with .[docker])
• Docker daemon running and accessible
• User has permission to access Docker (member of docker group or root)

Optional fields:

• docker_host: Custom Docker daemon URL (e.g., "tcp://192.168.1.100:2375" for remote Docker)

Features:

• Supports both JSON and plain text log formats
• Automatically infers severity from log messages (ERROR, WARN, INFO, DEBUG)
• Extracts rich container metadata (image, labels, status)
• Works with running and stopped containers

Example with remote Docker daemon:

{
  "name": "remote-app",
  "type": "docker",
  "container": "my-app",
  "docker_host": "tcp://192.168.1.100:2375"
}

GCP Cloud Logging Setup

To use GCP Cloud Logging as a log source:

1. Install with GCP support:

   pipx install logview-ag[all]  # or pip install logview-ag[all]
   

2. Authenticate with GCP:

   gcloud auth application-default login
   

3. Add a GCP context to your config:

   {
     "name": "my-gcp-project",
     "type": "gcp",
     "project": "your-project-id",
     "log_name": "cloudaudit.googleapis.com%2Factivity"
   }
   

Requirements:

• The google-cloud-logging package (installed with .[gcp])
• Valid Application Default Credentials (ADC)
• Logs Viewer role on the GCP project

Optional fields:

• log_name: Filter to specific log (e.g., cloudaudit.googleapis.com%2Factivity)
• resource_type: Filter by resource type (e.g., gce_instance, k8s_container)

GKE (Google Kubernetes Engine) Setup

GKE logs are stored in Cloud Logging, so LogView queries them via the Cloud Logging API with Kubernetes-specific resource filters.

1. Install with GCP support (same as GCP Cloud Logging):

   pipx install logview-ag[all]  # or pip install logview-ag[all]
   

2. Authenticate with GCP:

   gcloud auth application-default login
   

3. Add a GKE context to your config:

   {
     "name": "prod-cluster",
     "type": "gke",
     "project": "your-project-id",
     "cluster": "your-cluster-name",
     "location": "us-central1-a",
     "default_namespace": "default"
   }
   

Required fields:

• project: GCP project ID containing the cluster
• cluster: GKE cluster name

Optional fields:

• location: Cluster zone or region (e.g., us-central1-a)
• default_namespace: Default namespace filter

Filter fields (available in filter modal):

• namespace: Kubernetes namespace (supports wildcards: kube-*)
• pod: Pod name (supports wildcards: api-server-*)
• container: Container name
• labels: Pod labels in key=value,key2=value2 format

Security

Directory Allowlist

LogView restricts file access to a configurable allowlist of directories. This prevents:

• Path traversal attacks: Malicious paths like ../../../etc/passwd are blocked
• Symlink escapes: Symlinks pointing outside allowed directories are rejected
• Unauthorized access: Only explicitly permitted directories can be read

Default allowed directories: /var/log, /opt, /home

Security Note: The default /home permission is permissive—it allows reading any user's files that the process has permission to access. For production or multi-user systems, consider restricting this:

{
  "discovery": {
    "allowed_directories": ["/var/log", "/opt/myapp/logs"]
  }
}

To disable all file access (cloud-only mode), set an empty list:

{
  "discovery": {
    "allowed_directories": []
  }
}

Timestamps and Timezones

• Syslog (RFC 3164): Timestamps without timezone are interpreted as local time
• Syslog (RFC 5424/ISO 8601): Full timezone support (e.g., 2025-12-07T00:00:05-07:00)
• JSON Lines: ISO 8601 timestamps are parsed and displayed in local time

Troubleshooting

Common Issues

"Access denied" or "outside allowed directories"

• The file path is not within the configured allowed_directories
• Solution: Add the parent directory to allowed_directories in config, or move logs to an allowed location

"Log file not found"

• The file doesn't exist or the path is incorrect
• Solution: Verify the path with ls -la /path/to/file

"Permission denied" when reading logs

• The user running LogView doesn't have read permission
• Solution: Add your user to the appropriate group (e.g., sudo usermod -aG adm $USER for syslog on Ubuntu)

No logs appearing / empty list

• Filter may be too restrictive (wrong time range or severity)
• Solution: Press f to open filter, try "All Time" and "DEBUG" severity

Syslog timestamps showing wrong year

• RFC 3164 syslog format doesn't include year; the current year is assumed
• For accurate timestamps, configure rsyslog to use RFC 5424 format

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=src/logview

# Type checking
mypy src/

# Linting
ruff check src/ tests/

Documentation

• USER.md: Comprehensive user manual with detailed guides, workflows, and troubleshooting
• PLAN.md: Project roadmap and architecture documentation
• CHANGELOG.md: Detailed version history and changes
• ACTIONS.md: Development activity log

Project Status

This project is under active development. See PLAN.md for the roadmap.

• Phase 1: Foundation (MVP)
• Phase 2: Syslog & Modals
• Phase 3: Application Logs (logfile adapter with format auto-detection)
• Phase 4: GCP Cloud Logging
• Phase 5: GKE Integration
• Phase 6: Enhanced UX (help, search, export, filter presets, settings)
• Phase 7: Productionization (install.sh, wheel packaging)
• Phase 8: Additional Sources (AWS CloudWatch, Azure Monitor, Elasticsearch, etc.)

License

MIT