LogLens Documentation

Welcome to the official documentation for LogLens. Here you'll find everything you need to know to go from a beginner to a power user.

Installation

Install the latest version of LogLens using the method for your operating system.

macOS & Linux (via Homebrew) Recommended

If you have Homebrew installed, this is the easiest way to install and manage LogLens.

brew tap Caelrith/loglens
brew install loglens

macOS & Linux (via Shell)

curl -sSL https://download.getloglens.com/install.sh | sh

Windows (via PowerShell)

irm https://download.getloglens.com/install.ps1 | iex

The script will install the binary to a local directory and attempt to add it to your shell's PATH.

Once installed, you can keep LogLens up-to-date by running loglens update.

VS Code Extension

LogLens integrates directly into your editor, providing syntax highlighting for logs and the ability to run structured queries without switching context.

Installation

You can install the extension directly from the Visual Studio Marketplace.

ext install caelrith.loglens-vscode

View Extension on Marketplace

Features

Syntax Highlighting: Automatic highlighting for .log and .logfmt files.
Query: Run LogLens: Query Lines to filter logs into a new virtual document.
Watch: Run LogLens: Live Watch to tail logs in the Output panel.

Configuration

LogLens can be configured by creating a `config.toml` file in the application's configuration directory.

Config File Location:

Linux/macOS: ~/.config/loglens/config.toml
Windows: C:\Users\YourName\AppData\Roaming\loglens\config.toml

Customizing the TUI Display

The TUI needs to know which fields in your structured logs represent the timestamp, log level, and main message. You can define a prioritized list of keys for LogLens to check.

# Example ~/.config/loglens/config.toml

[tui]
# LogLens will check for "message", then "msg", then "text"
message_keys = ["message", "msg", "text"]

# It will check for "level", then "lvl", then "severity"
level_keys = ["level", "lvl", "severity"]

# It will check for "timestamp", then "ts", then "@timestamp"
timestamp_keys = ["timestamp", "ts", "@timestamp"]

Core Concept: Structured Logs

LogLens shines when working with structured logs. It automatically detects and parses JSON, Logfmt, and Nginx/Apache files.

JSON Example:

{"timestamp":"2025-08-26T10:00:00Z", "level":"error", "message":"User login failed", "user_id":"usr_123"}

Nginx & Apache Log Mapping

When LogLens detects a standard Nginx or Apache Access log, it parses the raw line and maps specific components to structured fields.

LogLens Field	Nginx Component	Description / Example
`timestamp`	`[$time_local]`	Parsed into ISO 8601 format for time comparisons.
`remote_addr`	`$remote_addr`	The client IP address.
`method`	`request_method`	Extracted HTTP Method (GET, POST).
`path`	`request_uri`	The requested URI path.
`status`	`$status`	HTTP Status Code (Numeric).
`body_bytes_sent`	`$body_bytes_sent`	Response size in bytes (Numeric).
`http_referer`	`$http_referer`	Referrer URL.
`http_user_agent`	`$http_user_agent`	The browser/client user agent string.
`level`	(Derived)	Calculated: `ERROR` (>= 500), `WARN` (>= 400), `INFO` (< 400).

Core Concept: Compressed Files

You don't need to decompress your .gz log files before analysis. LogLens handles them automatically. All commands that read logs will transparently decompress Gzip files on the fly.

# This works out-of-the-box, no extra flags needed!
loglens query "/var/log/archive/app-2025-08-27.log.gz" 'level == "error"'

Core Concept: Query Syntax

LogLens features a "Natural Query" engine designed to be readable and ergonomic.

Write Like You Speak

Goal	Query Example
Find specific levels	`level is "info"`
Filter by range	`status between 200..299`
Filter by time (Relative)	`timestamp > "5m ago"`
Search raw text	`text contains "timeout"`
Numeric text search	`text contains+ 500` (Finds nums >= 500 in text)
Combine logic	`env is "prod" and latency > 500`

Operator Reference

Equality: is, ==, isnot, !=
Comparison: >, <, >=, <=
Range: between, !between
Text: contains, !contains, ~= (regex match)
Existence: exists, !exists

Command Reference

`loglens search`

Search for a simple text pattern in log files. High-performance alternative to grep.

Argument	Description
`path`	[Required] The directory or file path to search in.
`term`	[Required] The text pattern to search for.
`-C, --context N`	Show N lines of context around a match.
`--json`	Output matching lines as compact JSON objects.
`--raw`	Output only raw log line (no filename/line numbers).

# Find "database timeout" and show 2 lines of context
loglens search ./logs "database timeout" -C 2

`loglens fields`

Discovers and lists all unique fields from your structured log files.

Argument	Description
`path`	[Required] The directory or file path to analyze.
`--details`	Show detailed information (types, examples).
`--sort-by`	Sort by 'name' or 'count'.
`--sample-size`	Number of lines to scan (Default: 1000).
`--full-scan`	Force scan all lines (slower but accurate).

loglens fields ./api_logs/ --details --sort-by count

`loglens query`

Query structured logs with an advanced query language.

Argument	Description
`path`	[Required] The directory or file path.
`query`	[Required] The query string (e.g., `'level == "error"'`).
`--since` / `--until`	Filter logs by time (e.g. "1h ago").
`--json`	Output matches as JSON.
`--raw`	Output matches as raw text.
`-C, -B, -A`	Context control (Around, Before, After).
`--squash`	Squash consecutive identical lines.

# Find all 5xx errors that happened in the last day
loglens query /var/log/ 'status_code >= 500' --since "1 day ago"

`loglens stats` PRO

Perform statistical analysis on log data.

Subcommand: `summary`

Provides a full, dynamic summary of the entire log dataset.

loglens stats ./logs/ summary --where 'timestamp >= "1h ago"'

Subcommand: `describe`

Provides a detailed statistical summary for a single numeric field.

loglens stats ./logs describe latency_ms --where 'service == "api"'

Subcommand: `group-by`

Groups entries by a categorical field and calculates statistics.

loglens stats ./logs/ group-by --by "endpoint" --avg "latency_ms"

`loglens count`

Quickly count the number of lines that match a query.

loglens count /var/log/ 'level is "critical"' --since "2h ago"

`loglens watch`

Watch files and tail logs in real-time, with server-side filtering.

Argument	Description
`path`	[Required] The directory or file path to watch.
`--where`	Query filter to apply.
`--highlight`	Comma-separated terms to highlight.
`--json`	Output as JSON.

loglens watch ./prod/api.log --where 'level == "error"' --highlight="timeout"

`loglens tui`

Start an interactive Terminal User Interface for log exploration.

Argument	Description
`path`	[Optional] Directory or file to explore.
`-f, --follow`	Follow file/folder for new entries.

loglens tui .

`loglens license`

Manage your LogLens Pro license.

loglens license activate YOUR-KEY
loglens license status
loglens license purchase

`loglens compress` / `decompress`

Utilities to handle Gzip files. Replaces original by default unless -o is used.

Argument	Description
`path`	[Required] File path.
`-o, --output`	Output path (keeps original file).

loglens compress large-app.log
loglens decompress archive.log.gz -o ./restored/

`loglens update`

Checks for a new version of LogLens and automatically updates it.

loglens update

`loglens docs`

Opens this documentation page in your default browser.

loglens docs

For Developers: The Rust Crate

LogLens is built on top of loglens-core, a high-performance, standalone Rust library.

Add to Cargo.toml

[dependencies]
loglens-core = "0.1.0"

Cookbook: Practical Recipes

Recipe: Debugging a 5XX Server Error

Problem: A spike in 5xx errors in the last hour.

# 1. Find the initial errors
loglens query ./logs/ 'status_code >= 500' --since "1h ago"

# 2. Trace a specific ID found in step 1
loglens search ./logs/ "trace_abc_123"

Recipe: Monitoring a Specific User

Problem: Watch a specific user's activity in real-time.

loglens watch /var/log/app.log --where 'user_id == "usr_fgh_456"'

Recipe: Analyzing API Endpoint Performance

Problem: Identify slow endpoints.

# 1. Get statistics for specific endpoint
loglens stats ./api_logs/ describe "response_time_ms" --where 'endpoint == "/api/v1/checkout"'

# 2. Compare all endpoints
loglens stats ./api_logs/ group-by --by "endpoint" --avg "latency_ms"

LogLens Documentation

Installation

macOS & Linux (via Homebrew) Recommended

macOS & Linux (via Shell)

Windows (via PowerShell)

VS Code Extension

Installation

Features

Configuration

Customizing the TUI Display

Core Concept: Structured Logs

Nginx & Apache Log Mapping

Core Concept: Compressed Files

Core Concept: Query Syntax

Write Like You Speak

Operator Reference

Command Reference

loglens search

loglens fields

loglens query

loglens stats PRO

Subcommand: summary

Subcommand: describe

Subcommand: group-by

loglens count

loglens watch

loglens tui

loglens license

loglens compress / decompress

loglens update

loglens docs

For Developers: The Rust Crate

Add to Cargo.toml

Cookbook: Practical Recipes

Recipe: Debugging a 5XX Server Error

Recipe: Monitoring a Specific User

Recipe: Analyzing API Endpoint Performance

`loglens search`

`loglens fields`

`loglens query`

`loglens stats` PRO

Subcommand: `summary`

Subcommand: `describe`

Subcommand: `group-by`

`loglens count`

`loglens watch`

`loglens tui`

`loglens license`

`loglens compress` / `decompress`

`loglens update`

`loglens docs`