# Log4Lab
A powerful, lightweight structured log viewer with live streaming, advanced filtering, and run tracking capabilities.
Log4Lab is a web-based dashboard for viewing and analyzing structured JSON logs in real-time. It provides a clean, modern interface for monitoring application logs with live updates, making it easy to track experiments, debug issues, and understand what's happening in your applications.
## Features
### Core Functionality
- **Live Log Streaming**: Automatically streams new log entries as they're written to the log file using Server-Sent Events (SSE)
- **Structured Log Support**: Parses and displays JSONL (JSON Lines) formatted logs
- **Relative Time Display**: Shows "how long ago" each entry was created with automatic updates
- **Dark Mode**: Built-in dark mode support with theme persistence in browser local storage
### Advanced Filtering
- **Level Filter**: Dynamically populated dropdown based on actual log levels in your file (case-insensitive)
- **Section Filter**: Filter by component or section name
- **Group Filter**: Filter by experiment or job group
- **Run Name Filter**: Filter by run name to see all runs in a collection
- **Run ID Filter**: Focus on a specific run instance
- **Time Range Filter**: View logs from the last 1 minute, 5 minutes, 1 hour, 6 hours, or 24 hours
- **URL-based Filters**: All filters can be passed as URL query parameters for bookmarking and sharing
### Run Management
- **Runs Index Page**: Hierarchical view showing all run names with their associated run IDs
- **Run Links**: Each log entry includes a clickable link to filter by its run name or run ID
- **Run Statistics**: See total log counts per run name and individual run ID
### Display & Navigation
- **Pagination**: Configurable page size (20, 50, 100, or 200 entries per page)
- **Sort Toggle**: Switch between newest-first and oldest-first ordering (perfect for reviewing run chronology)
- **Collapsible JSON**: Full JSON view available for each entry, collapsed by default
- **Smart Message Display**: Renders the `message` field as the main content in fixed-width font
- **Artifact Rendering**: Automatically displays images, PDFs, and files referenced in the `cache_path` field
### User Interface
- **Modern Design**: Built with Tailwind CSS for a clean, responsive interface
- **Smooth Navigation**: Scroll to top on page changes, smooth transitions
- **Keyboard-Friendly**: All filters and controls are easily accessible
## Installation
```bash
pip install log4lab
```
Or install from source:
```bash
git clone https://github.com/yourusername/log4lab.git
cd log4lab
pip install -e .
```
## Usage
Start the Log4Lab server:
```bash
log4lab serve [LOGFILE]
```
Or tail logs in the terminal:
```bash
log4lab tail [LOGFILE]
```
### Options
- `LOGFILE`: Path to the JSONL log file to stream (default: `logs/app.log`)
- `--host`: Host to bind to (default: `127.0.0.1`)
- `--port`: Port to listen on (default: `8000`)
- `--reload`: Enable auto-reload for development
### Examples
```bash
# Web server - Use default log file (logs/app.log)
log4lab serve
# Specify a custom log file
log4lab serve /path/to/your/app.log
# Run on a different port
log4lab serve myapp.log --port 3000
# Bind to all interfaces
log4lab serve myapp.log --host 0.0.0.0
# Development mode with auto-reload
log4lab serve --reload
# Terminal tail - live streaming to terminal
log4lab tail myapp.log
# Tail with filters
log4lab tail myapp.log --level=ERROR --open-images
```
Then open your browser to `http://localhost:8000` to view the dashboard.
### Using Filters via URL
Share specific filtered views by passing query parameters:
```bash
# View only ERROR logs
http://localhost:8000/?level=error
# View a specific run
http://localhost:8000/?run_id=abc123
# View all runs in a collection
http://localhost:8000/?run_name=model_training
# Combine multiple filters
http://localhost:8000/?level=error&run_name=experiment1&time=3600
```
## Log Format
Log4Lab expects logs in JSONL format (one JSON object per line). Each log entry should be a JSON object.
### Basic Example
```json
{"time": "2025-10-24T10:30:00Z", "level": "INFO", "section": "train", "message": "Training started"}
{"time": "2025-10-24T10:30:05Z", "level": "WARN", "section": "data", "message": "Missing data point"}
{"time": "2025-10-24T10:30:10Z", "level": "ERROR", "section": "model", "message": "Model failed to converge"}
```
### Advanced Example with Runs and Artifacts
```json
{
"time": "2025-10-24T10:30:00Z",
"level": "INFO",
"section": "train",
"message": "Training epoch 1 complete",
"run_name": "model_training",
"run_id": "run_001",
"group": "experiment_1",
"cache_path": "artifacts/training_plot.png",
"accuracy": 0.92,
"loss": 0.15
}
```
### Supported Fields
#### Core Fields
- `time`: Timestamp in ISO 8601 format (automatically handles UTC if no timezone specified)
- `level`: Log level (INFO, WARN, ERROR, DEBUG, etc.) - case-insensitive
- `section`: Component or section of your application
- `message` or `msg`: The main log message (displayed prominently in fixed-width font)
#### Run Tracking Fields
- `run_name`: Name of the run collection (e.g., "hyperparameter_search")
- `run_id`: Unique identifier for a specific run instance
- `group`: Group or experiment name for organizing related runs
#### Artifact Fields
- `cache_path`: Path to an artifact file (images, PDFs, etc.)
- Images (PNG, JPG, SVG, etc.) are displayed inline
- PDFs are embedded with a viewer
- Other files show as download links
#### Additional Fields
Any additional fields (metrics, parameters, etc.) are displayed in the expandable JSON view.
## Features in Detail
### Live Streaming
Log4Lab monitors the log file for changes and automatically streams new entries to the browser using Server-Sent Events (SSE). New entries appear at the top with smooth animations, and the "time ago" display updates every 5 seconds.
### Time Display
Each log entry shows:
- Relative time (e.g., "just now", "5m ago", "2h ago", "3d ago")
- Absolute timestamp for reference
- Automatic handling of UTC timestamps
- Smart future timestamp detection (shows "in 2h" for logs from the future)
### Filtering System
**Dynamic Level Filter**: Automatically discovers all log levels in your file and populates the dropdown. Supports any level names (INFO, Error, debug, WARN, etc.) with case-insensitive matching.
**Text Filters**: Section, Group, Run Name, and Run ID filters support partial matching and are case-insensitive.
**Time Range Filter**: Show only recent logs:
- Last 1 minute
- Last 5 minutes
- Last 10 minutes
- Last 30 minutes
- Last 1 hour
- Last 6 hours
- Last 24 hours
**Filter Persistence**: All filters are reflected in the URL, so you can bookmark specific views or share links with teammates.
### Run Management
The **Runs Index** (`/runs`) provides a bird's-eye view of all your runs:
- Lists all unique run names
- Shows total log count per run name
- Displays all associated run IDs with individual counts
- Click any run name to see all logs for that collection
- Click any run ID to see logs for that specific instance
Each log entry includes a **run info link** that takes you directly to a filtered view of that run.
### Sorting
Toggle between two sort orders:
- **Newest First** (default): Latest logs appear at the top - ideal for monitoring
- **Oldest First**: Chronological order from the beginning - perfect for understanding run progression
### Pagination
Control how many logs appear per page (20, 50, 100, or 200) and navigate through pages with Previous/Next buttons. The display shows your current position (e.g., "Showing 1-50 of 153 logs").
### Artifact Display
If your logs include a `cache_path` field pointing to artifacts:
**Images**: Displayed inline with full size
```json
{"cache_path": "artifacts/plot.png", "message": "Training loss over time"}
```
**PDFs**: Embedded with a document viewer
```json
{"cache_path": "artifacts/report.pdf", "message": "Experiment results"}
```
**Other Files**: Download link provided
```json
{"cache_path": "artifacts/model.pkl", "message": "Model checkpoint saved"}
```
### Theme Support
Toggle between light and dark modes with the theme button in the top-right corner. Your preference is saved in browser local storage and persists across sessions.
## Use Cases
### Machine Learning Experiments
Track training runs with metrics, visualizations, and hyperparameters:
```json
{"time": "2025-10-24T10:30:00Z", "level": "INFO", "run_name": "resnet_training", "run_id": "exp_001", "message": "Epoch 1/100", "loss": 0.45, "accuracy": 0.78, "cache_path": "plots/loss_curve.png"}
```
View all runs for a training session, compare metrics across runs, and review training progression chronologically.
### Distributed Systems Debugging
Monitor services across multiple components:
```json
{"time": "2025-10-24T10:30:00Z", "level": "ERROR", "section": "api", "group": "prod", "message": "Connection timeout to database", "duration_ms": 5000}
```
Filter by section to isolate component issues, use time range to focus on incident windows, and track error patterns.
### Research Workflows
Document experiments with notes and artifacts:
```json
{"time": "2025-10-24T10:30:00Z", "level": "INFO", "run_name": "parameter_sweep", "run_id": "sweep_042", "message": "Testing learning_rate=0.001", "cache_path": "results/metrics.pdf"}
```
Compare results across parameter sweeps, review experimental progression, and access generated reports directly from logs.
## Development
To run Log4Lab in development mode with auto-reload:
```bash
log4lab serve --reload
```
## Requirements
- Python >= 3.8
- FastAPI
- Uvicorn
- Jinja2
- Typer
## License
MIT
## Author
Thibaut Lamadon
Raw data
{
"_id": null,
"home_page": null,
"name": "log4lab",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "logging, log-viewer, structured-logs, jsonl, monitoring, dashboard, live-streaming",
"author": "Thibaut Lamadon",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/24/6b/ccecc8b78e6d483bbc139175528f47586154c32f7f4d85347ff205c58ee8/log4lab-0.1.0.tar.gz",
"platform": null,
"description": "# Log4Lab\n\nA powerful, lightweight structured log viewer with live streaming, advanced filtering, and run tracking capabilities.\n\nLog4Lab is a web-based dashboard for viewing and analyzing structured JSON logs in real-time. It provides a clean, modern interface for monitoring application logs with live updates, making it easy to track experiments, debug issues, and understand what's happening in your applications.\n\n## Features\n\n### Core Functionality\n- **Live Log Streaming**: Automatically streams new log entries as they're written to the log file using Server-Sent Events (SSE)\n- **Structured Log Support**: Parses and displays JSONL (JSON Lines) formatted logs\n- **Relative Time Display**: Shows \"how long ago\" each entry was created with automatic updates\n- **Dark Mode**: Built-in dark mode support with theme persistence in browser local storage\n\n### Advanced Filtering\n- **Level Filter**: Dynamically populated dropdown based on actual log levels in your file (case-insensitive)\n- **Section Filter**: Filter by component or section name\n- **Group Filter**: Filter by experiment or job group\n- **Run Name Filter**: Filter by run name to see all runs in a collection\n- **Run ID Filter**: Focus on a specific run instance\n- **Time Range Filter**: View logs from the last 1 minute, 5 minutes, 1 hour, 6 hours, or 24 hours\n- **URL-based Filters**: All filters can be passed as URL query parameters for bookmarking and sharing\n\n### Run Management\n- **Runs Index Page**: Hierarchical view showing all run names with their associated run IDs\n- **Run Links**: Each log entry includes a clickable link to filter by its run name or run ID\n- **Run Statistics**: See total log counts per run name and individual run ID\n\n### Display & Navigation\n- **Pagination**: Configurable page size (20, 50, 100, or 200 entries per page)\n- **Sort Toggle**: Switch between newest-first and oldest-first ordering (perfect for reviewing run chronology)\n- **Collapsible JSON**: Full JSON view available for each entry, collapsed by default\n- **Smart Message Display**: Renders the `message` field as the main content in fixed-width font\n- **Artifact Rendering**: Automatically displays images, PDFs, and files referenced in the `cache_path` field\n\n### User Interface\n- **Modern Design**: Built with Tailwind CSS for a clean, responsive interface\n- **Smooth Navigation**: Scroll to top on page changes, smooth transitions\n- **Keyboard-Friendly**: All filters and controls are easily accessible\n\n## Installation\n\n```bash\npip install log4lab\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/yourusername/log4lab.git\ncd log4lab\npip install -e .\n```\n\n## Usage\n\nStart the Log4Lab server:\n\n```bash\nlog4lab serve [LOGFILE]\n```\n\nOr tail logs in the terminal:\n\n```bash\nlog4lab tail [LOGFILE]\n```\n\n### Options\n\n- `LOGFILE`: Path to the JSONL log file to stream (default: `logs/app.log`)\n- `--host`: Host to bind to (default: `127.0.0.1`)\n- `--port`: Port to listen on (default: `8000`)\n- `--reload`: Enable auto-reload for development\n\n### Examples\n\n```bash\n# Web server - Use default log file (logs/app.log)\nlog4lab serve\n\n# Specify a custom log file\nlog4lab serve /path/to/your/app.log\n\n# Run on a different port\nlog4lab serve myapp.log --port 3000\n\n# Bind to all interfaces\nlog4lab serve myapp.log --host 0.0.0.0\n\n# Development mode with auto-reload\nlog4lab serve --reload\n\n# Terminal tail - live streaming to terminal\nlog4lab tail myapp.log\n\n# Tail with filters\nlog4lab tail myapp.log --level=ERROR --open-images\n```\n\nThen open your browser to `http://localhost:8000` to view the dashboard.\n\n### Using Filters via URL\n\nShare specific filtered views by passing query parameters:\n\n```bash\n# View only ERROR logs\nhttp://localhost:8000/?level=error\n\n# View a specific run\nhttp://localhost:8000/?run_id=abc123\n\n# View all runs in a collection\nhttp://localhost:8000/?run_name=model_training\n\n# Combine multiple filters\nhttp://localhost:8000/?level=error&run_name=experiment1&time=3600\n```\n\n## Log Format\n\nLog4Lab expects logs in JSONL format (one JSON object per line). Each log entry should be a JSON object.\n\n### Basic Example\n\n```json\n{\"time\": \"2025-10-24T10:30:00Z\", \"level\": \"INFO\", \"section\": \"train\", \"message\": \"Training started\"}\n{\"time\": \"2025-10-24T10:30:05Z\", \"level\": \"WARN\", \"section\": \"data\", \"message\": \"Missing data point\"}\n{\"time\": \"2025-10-24T10:30:10Z\", \"level\": \"ERROR\", \"section\": \"model\", \"message\": \"Model failed to converge\"}\n```\n\n### Advanced Example with Runs and Artifacts\n\n```json\n{\n \"time\": \"2025-10-24T10:30:00Z\",\n \"level\": \"INFO\",\n \"section\": \"train\",\n \"message\": \"Training epoch 1 complete\",\n \"run_name\": \"model_training\",\n \"run_id\": \"run_001\",\n \"group\": \"experiment_1\",\n \"cache_path\": \"artifacts/training_plot.png\",\n \"accuracy\": 0.92,\n \"loss\": 0.15\n}\n```\n\n### Supported Fields\n\n#### Core Fields\n- `time`: Timestamp in ISO 8601 format (automatically handles UTC if no timezone specified)\n- `level`: Log level (INFO, WARN, ERROR, DEBUG, etc.) - case-insensitive\n- `section`: Component or section of your application\n- `message` or `msg`: The main log message (displayed prominently in fixed-width font)\n\n#### Run Tracking Fields\n- `run_name`: Name of the run collection (e.g., \"hyperparameter_search\")\n- `run_id`: Unique identifier for a specific run instance\n- `group`: Group or experiment name for organizing related runs\n\n#### Artifact Fields\n- `cache_path`: Path to an artifact file (images, PDFs, etc.)\n - Images (PNG, JPG, SVG, etc.) are displayed inline\n - PDFs are embedded with a viewer\n - Other files show as download links\n\n#### Additional Fields\nAny additional fields (metrics, parameters, etc.) are displayed in the expandable JSON view.\n\n## Features in Detail\n\n### Live Streaming\n\nLog4Lab monitors the log file for changes and automatically streams new entries to the browser using Server-Sent Events (SSE). New entries appear at the top with smooth animations, and the \"time ago\" display updates every 5 seconds.\n\n### Time Display\n\nEach log entry shows:\n- Relative time (e.g., \"just now\", \"5m ago\", \"2h ago\", \"3d ago\")\n- Absolute timestamp for reference\n- Automatic handling of UTC timestamps\n- Smart future timestamp detection (shows \"in 2h\" for logs from the future)\n\n### Filtering System\n\n**Dynamic Level Filter**: Automatically discovers all log levels in your file and populates the dropdown. Supports any level names (INFO, Error, debug, WARN, etc.) with case-insensitive matching.\n\n**Text Filters**: Section, Group, Run Name, and Run ID filters support partial matching and are case-insensitive.\n\n**Time Range Filter**: Show only recent logs:\n- Last 1 minute\n- Last 5 minutes\n- Last 10 minutes\n- Last 30 minutes\n- Last 1 hour\n- Last 6 hours\n- Last 24 hours\n\n**Filter Persistence**: All filters are reflected in the URL, so you can bookmark specific views or share links with teammates.\n\n### Run Management\n\nThe **Runs Index** (`/runs`) provides a bird's-eye view of all your runs:\n- Lists all unique run names\n- Shows total log count per run name\n- Displays all associated run IDs with individual counts\n- Click any run name to see all logs for that collection\n- Click any run ID to see logs for that specific instance\n\nEach log entry includes a **run info link** that takes you directly to a filtered view of that run.\n\n### Sorting\n\nToggle between two sort orders:\n- **Newest First** (default): Latest logs appear at the top - ideal for monitoring\n- **Oldest First**: Chronological order from the beginning - perfect for understanding run progression\n\n### Pagination\n\nControl how many logs appear per page (20, 50, 100, or 200) and navigate through pages with Previous/Next buttons. The display shows your current position (e.g., \"Showing 1-50 of 153 logs\").\n\n### Artifact Display\n\nIf your logs include a `cache_path` field pointing to artifacts:\n\n**Images**: Displayed inline with full size\n```json\n{\"cache_path\": \"artifacts/plot.png\", \"message\": \"Training loss over time\"}\n```\n\n**PDFs**: Embedded with a document viewer\n```json\n{\"cache_path\": \"artifacts/report.pdf\", \"message\": \"Experiment results\"}\n```\n\n**Other Files**: Download link provided\n```json\n{\"cache_path\": \"artifacts/model.pkl\", \"message\": \"Model checkpoint saved\"}\n```\n\n### Theme Support\n\nToggle between light and dark modes with the theme button in the top-right corner. Your preference is saved in browser local storage and persists across sessions.\n\n## Use Cases\n\n### Machine Learning Experiments\n\nTrack training runs with metrics, visualizations, and hyperparameters:\n\n```json\n{\"time\": \"2025-10-24T10:30:00Z\", \"level\": \"INFO\", \"run_name\": \"resnet_training\", \"run_id\": \"exp_001\", \"message\": \"Epoch 1/100\", \"loss\": 0.45, \"accuracy\": 0.78, \"cache_path\": \"plots/loss_curve.png\"}\n```\n\nView all runs for a training session, compare metrics across runs, and review training progression chronologically.\n\n### Distributed Systems Debugging\n\nMonitor services across multiple components:\n\n```json\n{\"time\": \"2025-10-24T10:30:00Z\", \"level\": \"ERROR\", \"section\": \"api\", \"group\": \"prod\", \"message\": \"Connection timeout to database\", \"duration_ms\": 5000}\n```\n\nFilter by section to isolate component issues, use time range to focus on incident windows, and track error patterns.\n\n### Research Workflows\n\nDocument experiments with notes and artifacts:\n\n```json\n{\"time\": \"2025-10-24T10:30:00Z\", \"level\": \"INFO\", \"run_name\": \"parameter_sweep\", \"run_id\": \"sweep_042\", \"message\": \"Testing learning_rate=0.001\", \"cache_path\": \"results/metrics.pdf\"}\n```\n\nCompare results across parameter sweeps, review experimental progression, and access generated reports directly from logs.\n\n## Development\n\nTo run Log4Lab in development mode with auto-reload:\n\n```bash\nlog4lab serve --reload\n```\n\n## Requirements\n\n- Python >= 3.8\n- FastAPI\n- Uvicorn\n- Jinja2\n- Typer\n\n## License\n\nMIT\n\n## Author\n\nThibaut Lamadon\n",
"bugtrack_url": null,
"license": null,
"summary": "A lightweight structured log viewer with live streaming and filters.",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/tlamadon/log4lab",
"Issues": "https://github.com/tlamadon/log4lab/issues",
"Repository": "https://github.com/tlamadon/log4lab"
},
"split_keywords": [
"logging",
" log-viewer",
" structured-logs",
" jsonl",
" monitoring",
" dashboard",
" live-streaming"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ee0ae3c362c035710dd928a3a6a9f257495031dc445e7ae7d67861f5b29cc205",
"md5": "880e6e798fc914f3d1fe83c900b57fc1",
"sha256": "c437d27ebacaf1c079a27a18472e416ce521798dc9dcc2f8b3106d26d90e9f93"
},
"downloads": -1,
"filename": "log4lab-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "880e6e798fc914f3d1fe83c900b57fc1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 22442,
"upload_time": "2025-10-28T14:31:34",
"upload_time_iso_8601": "2025-10-28T14:31:34.029805Z",
"url": "https://files.pythonhosted.org/packages/ee/0a/e3c362c035710dd928a3a6a9f257495031dc445e7ae7d67861f5b29cc205/log4lab-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "246bccecc8b78e6d483bbc139175528f47586154c32f7f4d85347ff205c58ee8",
"md5": "ea5356d33122d3a8eada991a3269abe0",
"sha256": "b2f1fc4a35b63be931070c56e44f87c563f32fb13d5654baa3ec981a364ffdb8"
},
"downloads": -1,
"filename": "log4lab-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "ea5356d33122d3a8eada991a3269abe0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24067,
"upload_time": "2025-10-28T14:31:35",
"upload_time_iso_8601": "2025-10-28T14:31:35.241043Z",
"url": "https://files.pythonhosted.org/packages/24/6b/ccecc8b78e6d483bbc139175528f47586154c32f7f4d85347ff205c58ee8/log4lab-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-28 14:31:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tlamadon",
"github_project": "log4lab",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "log4lab"
}
JSON
