Features

• Zero-Fuss Integration: Discovers log files and formatters directly from your standard Django LOGGING configuration.

• Log Analytics Dashboard: - KPI Metrics Cards: Total logs, file sizes, error counts, error rate percentage, warning, info, and debug counts. - 24-Hour Activity & Surge Histogram: Visual hourly traffic distribution across the day with error highlights and peak volume surge alerts. - File Switcher Bar: Visual interactive pill buttons displaying each available log file with file size badges for quick one-click switching. - Auto-Refresh: Live polling intervals (off, 5s, 10s, 30s, 60s) with spinning status indicators.

• Request & Transaction Trace Scanner: - Trace any ID across logs: Request ID, Correlation ID, Trace ID, User ID, Task ID, Order ID, or UUID. - Date Scoping: Selected log file, all available files, or custom date range (start to end date). - Fast Mode / Severity pre-filtering: target specific log levels (e.g. ERROR) to accelerate scans. - Lifecycle Event Timeline: Automatically maps log events to structured lifecycle stages (Drafting/Creation, Scheduling, Approval, Queue & Processing, Dispatch/Delivery, Completion, Failures/Errors) with color-coded stage badges and interactive step inspection.

• Massive Payload Sanitization & DOM Protection: - Automatically redacts voluminous JSON dumps, base64 blobs, and large arrays into concise interactive indicator pills in the list view (e.g. [/* 📦 Array (500 items) stripped */], [/* 📦 Object (8,109 chars) stripped */]). - Full raw payload is preserved and viewable on-demand in the Log Detail Modal with one-click JSON formatting and clipboard copying. - Sensitive credentials masking (Authorization Bearer tokens, passwords).

• Fast Filtering & Search: Instant severity tabs (ALL, ERROR, WARN, INFO, DEBUG), real-time debounced keyword search with match highlighting, and pagination.

• Export Capabilities: Export filtered logs as JSON or CSV directly from the dashboard.

• Universal Log Format Support: - Supports %-style (%(asctime)s), {-style ({asctime}), and $-style ($asctime) formatters. - Automatically parses bracketed timestamps ([%(asctime)s]), hyphen delimiters, colons, and padded levels (%(levelname)-8s). - Handles Django documentation’s recommended formats seamlessly (including {process:d}, {thread:d}).

• Multiline Traceback Preservation: Multi-line error stack traces and exceptions are automatically attached to their corresponding log entries and rendered cleanly with preserved formatting.

• Rotated Logs Support: Seamlessly browses rotated log archives (e.g. app.log.1, app.log.2023-11-22).

• Pathlib & Relative Path Support: Works seamlessly with pathlib.Path objects (e.g., BASE_DIR / 'logs' / 'app.log') and relative paths.

• Secure Access Control (RBAC): Restricted to superusers by default, or fully customizable with custom permission functions and staff controls.

• Dual View Modes: Sleek dark-mode Analytics Dashboard by default with instant toggle to Classic DataTables view.

Compatibility

• Python: 3.11, 3.12, 3.13+

• Django: 4.2 (LTS), 5.0, 5.1, 5.2+

Installation

Install via pip:

pip install django-simple-log-viewer

Quick Start

1. Add log_viewer to your INSTALLED_APPS in settings.py:

   INSTALLED_APPS = [
       ...,
       'log_viewer',
   ]

2. Add the log viewer to your project’s urls.py:

   from django.urls import path, include
   
   urlpatterns = [
       ...,
       path('log-viewer/', include('log_viewer.urls')),
   ]

3. Configure a file-based handler in your LOGGING setting in settings.py (if you haven’t already):

   from pathlib import Path
   BASE_DIR = Path(__file__).resolve().parent.parent
   
   LOGGING = {
       'version': 1,
       'disable_existing_loggers': False,
       'formatters': {
           'verbose': {
               'format': '{levelname} {asctime} {module} {process:d} {thread:d} {message}',
               'style': '{',
           },
           'standard': {
               'format': '%(asctime)s [%(levelname)s] %(name)s: %(message)s',
           },
       },
       'handlers': {
           'file': {
               'level': 'DEBUG',
               'class': 'logging.FileHandler',
               'filename': BASE_DIR / 'app.log',
               'formatter': 'standard',
           },
       },
       'loggers': {
           '': {
               'handlers': ['file'],
               'level': 'INFO',
               'propagate': True,
           },
       },
   }

4. Log in as a superuser and visit /log-viewer/ in your browser.

Settings Configuration

Every behavior and tweak of the log dashboard can be configured in your settings.py:

LOG_VIEWER_ENTITY_PATTERNS = [
    r'(?i)\b(?:request|request_id|trace_id)[\s:=#]+([a-zA-Z0-9_\-]+)',
    r'(?i)\b(?:correlation|correlation_id)[\s:=#]+([a-zA-Z0-9_\-]+)',
    r'(?i)\b(?:user|user_id)[\s:=#]+([a-zA-Z0-9_\-]+)',
    r'#([a-zA-Z0-9_\-]+)',
]

LOG_VIEWER_LIFECYCLE_STAGES = [
    {'name': 'Creation', 'color': 'blue', 'keywords': ['create', 'created', 'init']},
    {'name': 'Queueing', 'color': 'cyan', 'keywords': ['queue', 'queued', 'worker']},
    {'name': 'Processing', 'color': 'indigo', 'keywords': ['process', 'running']},
    {'name': 'Dispatch', 'color': 'teal', 'keywords': ['send', 'sent', 'broadcast']},
    {'name': 'Completion', 'color': 'green', 'keywords': ['success', 'completed', 'done']},
    {'name': 'Errors', 'color': 'red', 'keywords': ['fail', 'failed', 'error', 'fatal']},
]

REST API Endpoints Reference

All API endpoints inherit your RBAC permissions and return JSON:

Running Tests

To run the test suite:

python3 runtests.py

License

Released under the MIT License.