logview-ag 0.8.0
A testable, responsive log viewer TUI with pluggable log source contexts
License: MIT
Requires Python: >=3.11
Keywords: gcp, gke, logs, monitoring, syslog, textual, tui, viewer

# LogView

[![CI](https://github.com/agileguy/logview/actions/workflows/ci.yml/badge.svg)](https://github.com/agileguy/logview/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/logview-ag.svg)](https://pypi.org/project/logview-ag/)
[![Python](https://img.shields.io/pypi/pyversions/logview-ag.svg)](https://pypi.org/project/logview-ag/)

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

[![PyPI version](https://img.shields.io/pypi/v/logview-ag.svg)](https://pypi.org/project/logview-ag/)

### Quick Install (Recommended)

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

# Or using pip
pip install logview-ag
```

### With Optional Dependencies

```bash
# 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)

```bash
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:

```bash
# 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

```bash
# 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

```bash
# 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`:

```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:

```json
{
  "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:
```bash
tail -f ~/.config/logview/logview.log
```

### Docker Container Logs Setup

To view logs from Docker containers:

1. **Install with Docker support**:
   ```bash
   pipx install logview-ag[docker]  # or pip install logview-ag[docker]
   ```

2. **Ensure Docker is running**:
   ```bash
   docker info  # Should connect successfully
   ```

3. **Add a Docker context to your config**:
   ```json
   {
     "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**:
```json
{
  "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**:
   ```bash
   pipx install logview-ag[all]  # or pip install logview-ag[all]
   ```

2. **Authenticate with GCP**:
   ```bash
   gcloud auth application-default login
   ```

3. **Add a GCP context to your config**:
   ```json
   {
     "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):
   ```bash
   pipx install logview-ag[all]  # or pip install logview-ag[all]
   ```

2. **Authenticate with GCP**:
   ```bash
   gcloud auth application-default login
   ```

3. **Add a GKE context to your config**:
   ```json
   {
     "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:

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

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

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

```bash
# 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](USER.md)**: Comprehensive user manual with detailed guides, workflows, and troubleshooting
- **[PLAN.md](PLAN.md)**: Project roadmap and architecture documentation
- **[CHANGELOG.md](CHANGELOG.md)**: Detailed version history and changes
- **[ACTIONS.md](ACTIONS.md)**: Development activity log

## Project Status

This project is under active development. See [PLAN.md](PLAN.md) for the roadmap.

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

## License

MIT