Structured Logs Viewer

A modern, web-based log viewer built with Next.js for analyzing and filtering structured application logs. Perfect for development, debugging, and monitoring applications that generate structured log files.

---

✨ Features

• 📁 Multi-file Support - Automatically reads and combines multiple log files
• 🔍 Advanced Filtering - Filter by log level (INFO, ERROR, WARNING, etc.) and source file
• 🔎 Full-text Search - Search across messages, modules, and timestamps
• 📊 Clean Interface - View logs in an organized table with syntax highlighting
• 🔄 Real-time Refresh - Reload logs on demand to see latest entries
• 📝 Multi-line Log Support - Properly handles stack traces and multi-line entries
• ⚡ Fast & Responsive - Built with performance in mind using Next.js App Router
• 🎨 Modern UI - Beautiful, responsive design with Tailwind CSS

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn

Installation

1. Clone the repository:

git clone https://github.com/shozibabbas/structured-logs-viewer.git
cd structured-logs-viewer

2. Install dependencies:

npm install

3. Start the development server:

npm run dev

4. Open http://localhost:3000 in your browser

📖 Usage

Adding Log Files

Place your .log files in the logs/ directory at the project root:

structured-logs-viewer/
├── logs/
│   ├── application.log
│   ├── errors.log
│   ├── debug.log
│   └── access.log
├── app/
├── lib/
└── ...

Supported Log Format

The viewer expects logs in the following pipe-delimited format:

YYYY-MM-DD HH:MM:SS,mmm | LEVEL | module_name | message

Example:

2026-01-30 14:32:15,123 | INFO | auth.service | User authentication successful
2026-01-30 14:32:16,456 | ERROR | db.connection | Connection timeout after 30s
2026-01-30 14:32:17,789 | WARNING | cache.redis | Cache miss for key: user_session_abc123

Supported Log Levels:

• INFO
• WARNING / WARN
• ERROR
• DEBUG
• CRITICAL / FATAL

Generating Compatible Logs

Python

Configure Python's logging module to output in the expected format:

import logging
import os

# Set log level from environment or default to INFO
LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO").upper()

# Configure logging format to match the viewer's expected format
logging.basicConfig(
    level=LOG_LEVEL,
    format="%(asctime)s | %(levelname)s | %(name)s | %(message)s"
)

# Create logger for your module
log = logging.getLogger("your_module_name")

# Use it in your code
log.info("Application started successfully")
log.warning("Cache miss for key: %s", cache_key)
log.error("Database connection failed: %s", error_message)

JavaScript/Node.js

Using popular logging libraries like Winston or Pino:

const winston = require('winston');

const logger = winston.createLogger({
  format: winston.format.combine(
    winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss,SSS' }),
    winston.format.printf(({ timestamp, level, message }) => {
      return `${timestamp} | ${level.toUpperCase()} | ${process.env.MODULE_NAME || 'app'} | ${message}`;
    })
  ),
  transports: [
    new winston.transports.File({ filename: 'logs/application.log' })
  ]
});

logger.info('User authentication successful');
logger.error('Connection timeout after 30s');

Other Languages

The key is to use a format string that outputs:

1. Timestamp in YYYY-MM-DD HH:MM:SS,mmm format
2. Pipe separator (|)
3. Log level (INFO, ERROR, etc.)
4. Pipe separator (|)
5. Module/logger name
6. Pipe separator (|)
7. Message

Multi-line Logs & Stack Traces

The parser automatically handles multi-line log entries, such as stack traces:

2026-01-30 14:35:42,123 | ERROR | api.handler | Request failed with exception
Traceback (most recent call last):
  File "/app/api/handler.py", line 42, in process_request
    result = process_data(request.body)
ValueError: Invalid input format

Viewing Logs

1. Navigate to http://localhost:3000
2. Click "View Logs"
3. Use the filters and search bar to find specific entries
4. Click "Refresh" to reload logs from disk

🛠️ API Reference

GET /api/logs

Retrieves all parsed log entries from the logs/ directory.

Response:

{
  "logs": [
    {
      "timestamp": "2026-01-30 14:32:15,123",
      "level": "INFO",
      "module": "auth.service",
      "message": "User authentication successful",
      "fileName": "application.log",
      "rawLine": "2026-01-30 14:32:15,123 | INFO | auth.service | User authentication successful",
      "lineNumber": 42,
      "packetId": "packet_1_2026-01-30 14:32:10,000",
      "isPacketStart": false,
      "isPacketEnd": false
    }
  ],
  "totalEntries": 1523,
  "files": ["application.log", "errors.log"],
  "packets": ["packet_1_2026-01-30 14:32:10,000", "packet_2_2026-01-30 14:45:22,100"],
  "settings": {
    "enablePackets": true,
    "packetStartPattern": "Received message on",
    "packetEndPattern": "Processed OK"
  }
}

GET /api/settings

Retrieves current log parsing settings.

Response:

{
  "settings": {
    "id": 1,
    "enablePackets": true,
    "packetStartPattern": "Received message on",
    "packetEndPattern": "Processed OK",
    "createdAt": "2026-01-30 12:00:00",
    "updatedAt": "2026-01-30 12:30:00"
  }
}

PUT /api/settings

Updates log parsing settings.

Request Body:

{
  "enablePackets": true,
  "packetStartPattern": "Received message on",
  "packetEndPattern": "Processed OK"
}

Response:

{
  "settings": {
    "id": 1,
    "enablePackets": true,
    "packetStartPattern": "Received message on",
    "packetEndPattern": "Processed OK",
    "createdAt": "2026-01-30 12:00:00",
    "updatedAt": "2026-01-30 12:35:00"
  },
  "message": "Settings updated successfully"
}

Error Responses:

• 404 - Logs directory not found
• 500 - Failed to read log files

📂 Project Structure

structured-logs-viewer/
├── app/
│   ├── api/
│   │   ├── logs/
│   │   │   └── route.ts          # API endpoint for reading logs
│   │   └── settings/
│   │       └── route.ts          # API endpoint for settings
│   ├── logs/
│   │   └── page.tsx              # Main logs viewer interface
│   ├── settings/
│   │   └── page.tsx              # Settings configuration page
│   ├── layout.tsx                # Root layout
│   ├── page.tsx                  # Landing page
│   └── globals.css               # Global styles
├── lib/
│   ├── logParser.ts              # Log parsing utilities
│   └── database.ts               # SQLite database management
├── logs/                         # Place your .log files here
│   └── sample.log                # Example log file
├── data/                         # SQLite database (auto-generated)
│   └── settings.db
├── public/                       # Static assets
├── package.json
├── tsconfig.json
├── next.config.ts
└── README.md

🧪 Development

Build for Production

npm run build
npm start

Run Linter

npm run lint

Type Checking

npx tsc --noEmit

🎨 Customization

Change Log Directory

By default, logs are read from the logs/ directory. To use a different location, modify the path in app/api/logs/route.ts:

const logsDir = path.join(process.cwd(), 'your-logs-directory');

Custom Log Format

To support a different log format, update the regex pattern in lib/logParser.ts:

const logPattern = /your-custom-pattern/;

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Next.js
• Styled with Tailwind CSS
• Icons from Heroicons

📧 Contact

Project Link: https://github.com/shozibabbas/structured-logs-viewer

---

Made with ❤️ for developers who love clean logs