EasyLogs

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 26 Open GitHub ↗

The simple, agnostic and lightweight logging dashboard

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# EasyLogs - The simple, agnostic and lightweight logging dashboard

![License](https://img.shields.io/badge/License-Apache2-SUCCESS)

![Logo](https://raw.githubusercontent.com/cr0hn/easylogs/main/images/logo-250x250.jpg)

In a nutshell ``EasyLogs`` is a simple, but powerful, dashboard to visualize logs.

- [EasyLogs - The simple, agnostic and lightweight logging dashboard](#easylogs---the-simple-agnostic-and-lightweight-logging-dashboard)

- [What is EasyLogs?](#what-is-easylogs)
  - [Main features](#main-features)
  - [Why not...](#why-not)
  - [EasyLogs is for you if...](#easylogs-is-for-you-if)
- [Some screenshots](#some-screenshots)
  - [Desktop](#desktop)
  - [Mobile](#mobile)
  - [Installing EasyLogs as a PWA](#installing-easylogs-as-a-pwa)
- [Deployment](#deployment)
  - [Configuration](#configuration)
  - [Docker (standalone)](#docker-standalone)
  - [Docker (external MongoDB & Redis)](#docker-external-mongodb--redis)
  - [Docker Compose](#docker-compose)
- [Connecting to EasyLogs](#connecting-to-easylogs)
- [How to log to EasyLogs?](#how-to-log-to-easylogs)
  - [Python](#python)
    - [Python HTTP Handler (default implementation)](#python-http-handler-default-implementation)
    - [Python HTTP Handler (fault-tolerant version)](#python-http-handler-fault-tolerant-version)
  - [Java (NOT IMPLEMENTED)](#java-not-implemented)
  - [Go (NOT IMPLEMENTED)](#go-not-implemented)
  - [NodeJS (NOT IMPLEMENTED)](#nodejs-not-implemented)
  - [C# (NOT IMPLEMENTED)](#c-not-implemented)
  - [Ruby (NOT IMPLEMENTED)](#ruby-not-implemented)
- [Contributing](#contributing)
  - [Adding new loggers](#adding-new-loggers)
  - [Adding new loggers + API](#adding-new-loggers--api)
- [TODO](#todo)
- [License](#license)
- [Acknowledgments](#acknowledgments)

# What is EasyLogs?

EasyLogs is a agnostic dashboard for display and filter logs. It can be used with any log source.

The main idea is to provide a simple and lightweight dashboard to visualize logs that you can use quickly.

## Main features

- Real-time logs.
- Simple dashboard interface.
- Filter logs by level, date, message, etc.
- Text search in logs messages.
- Log aggregation.
- Mobile-first design.
- [PWA](https://en.wikipedia.org/wiki/Progressive_web_app) support (See images below).

## Why not...

There are a lot of log dashboards out there:

- Kibana
- Graylog
- Splunk
- Logstash
- ...

But most of them are very complex to configure and use. EasyLogs is a simple dashboard that can be used with any log source.

## EasyLogs is for you if...

- You want to use a simple dashboard.
- You want to visualize logs in a simple way.
- You want only a basic logs filtering.
- You want a fast deployment and lightweight dashboard.
- You don't need a complex log dashboard.
- You don't want to spend time configuring a log dashboard.
- You don't need analytics of your logs.

# Some screenshots

## Desktop

![Screenshot 1](https://raw.githubusercontent.com/cr0hn/easylogs/main/images/screenshot-001.png)

![Screenshot 2](https://raw.githubusercontent.com/cr0hn/easylogs/main/images/screenshot-002.png)

![Screenshot 3](https://raw.githubusercontent.com/cr0hn/easylogs/main/images/screenshot-003.png)

## Mobile

## Installing EasyLogs as a PWA

# Deployment

EasyLogs is composed by:

- The Web Application, aka, the Dashboard.
- MongoDB database for storing logs.
- Redis database for storing sessions.

So, you need to have both running.

## Configuration

EasyLogs is configured using environment variables. This table shows all the available configuration options:

| Variable | Description                | Default value |
| --- |----------------------------| -- |
| `REDIS_URI` | Redis Connection string | `redis://127.0.0.1:6379/0` |
| `MONGO_DB` | MongoDB database | `easylogs` |
| `MONGO_URI` | MongoDB Connection string | `mongodb://root:example@127.0.0.1:27099` |
| `ADMIN_USER` | Admin user | `admin` |
| `ADMIN_PASSWORD` | Admin Password | `adminadmin` |
| `RECEIVE_LOGS_KEY` | Key used to authenticate loggers  | `LIh982y87GgljahsadfklJHLIUG87g1u1e7f6eb2ee145571858e8e24` |
| `EMBEDED_DB` | If this variable is set, enables MongoDB and Redis embedded databases. Allowed values: TRUE|TRUE | Not set |

> NOTE: If you want to use MongoDB embedded database, you don't need to set `MONGO_URI` and `MONGO_DB` variables.

> Currently, EasyLogs only support fixed authentication. In the future, we will add support for other authentication methods.

## Docker (standalone)

Easylog has the possibility to run MongoDB and the Web Application in the same container. This is the easiest way to run EasyLogs.

```bash
> docker run -e EMBEDED_DB=1 -p 8080:8080 cr0hn/easylogs
```

> NOTE: Not recommended for production environments.

## Docker (external MongoDB & Redis)

If you want to run EasyLogs in a production environment, you should use an external MongoDB & Redis databases.

```bash
> export MONGO_URI=mongodb://...
> export REDIS_URI=redis://...
> docker run -e MONGODB_URI=$MONGODB_URI -e REDIS_URI=$REDIS_URI -p 8080:8080 cr0hn/easylogs
```

> NOTE: If you don't want to deploy and maintain a MongoDB, you can use a [MongoDB Atlas](https://www.mongodb.com/atlas/database) cloud database. It's free, simple and fast.
> NOTE: If you don't want to deploy and maintain a Redis, you can use a [Redis Labs](https://redislabs.com/) cloud database. It's free, simple and fast.

## Docker Compose

You can use the provided ``docker-compose.yaml`` file to run EasyLogs with an external MongoDB database.

```bash
> export MONGO_INITDB_ROOT_USERNAME=root
> export MONGO_INITDB_ROOT_PASSWORD=example
> docker-compose -p easy-logs up -d
```

> NOTE: If you want to expose MongoDB & Redis ports, be sure you add the ``ports:`` section in the ``docker-compose.yaml`` file.

# Connecting to EasyLogs

Once you have EasyLogs running, you can connect to it using the default credentials (Unless you have changed them):

- User: ``admin``
- Password: ``adminadmin``

Then you can connect to the dashboard using the URL: ``http://localhost:8080``

# How to log to EasyLogs?

EasyLogs can be used with any log source.

## Python

### Python HTTP Handler (default implementation)

Python has a builtin [HTTP Handler log](https://docs.python.org/3/library/logging.handlers.html#logging.handlers.HTTPHandler) that can be used to send logs to EasyLogs:

```python
"""
This file configures a logger and sent the log to a remote HTTP server.
"""

from urllib.parse import urlparse

import logging
import logging.handlers

def get_log(name: str): 
  # Get new logger
  logging.basicConfig()

logger = logging.getLogger(name)
  
  # Configure logger to send logs to EasyLogs
  easy_logs_host = "http://localhost:8080"
  easy_logs_path = "/loggers/python/http-handler"
  easy_logs_token = "LIh982y87GgljahsadfklJHLIUG87g1u1e7f6eb2ee145571858e8e24"
  
  parsed_url = urlparse(easy_logs_host)
  
  # Create HTTP handler
  http_handler = logging.handlers.HTTPHandler(
    parsed_url.netloc,
    f'{easy_logs_path}?key={easy_logs_token}',
    method='POST',
    secure=True if parsed_url.scheme == "https" else False
  )
  logger.addHandler(http_handler)
  
  return logger

logger = get_log("easylogs")
logger.setLevel(logging.DEBUG)

# Send logs
logger.info('This is a test log message')

try:
    1 / 0
except Exception as e:
    logger.error('Error', exc_info=e, extra={'foo': 'bar'}, stack_info=True)
    logger.exception("asdf", e)
```

> WARNING: The default handler doesn't manager connections errors. Bot a better resilient HTTP handler see next point.

### Python HTTP Handler (fault-tolerant version)

This is a fault-tolerant HTTP handler for send logs. If server doesn't responds, keep the logs and try again later.

```python
from urllib.parse import urlparse

import queue
import logging
import logging.handlers

#
# This is the HTTP Handler for a resilient log client
#
class HTTPHandlerResilient(logging.handlers.HTTPHandler):
    def __init__(self, host, url, method='GET', secure=True):
        super().__init__(host, url, method, secure)
        self._queue = queue.Queue()

def emit(self, record):
        try:
            super().emit(record)

# If not error, try to send any remaining messages
            while True:
                try:
                    super().emit(self._queue.get_nowait())
                except queue.Empty:
                    break

except ConnectionError:
            self._queue.put(record)

def handleError(self, record):
        raise ConnectionError()

def get_log(name: str): 
  # Get new logger
  logging.basicConfig()

logger = logging.getLogger(name)
  
  # Configure logger to send logs to EasyLogs
  easy_logs_host = "http://localhost:8080"
  easy_logs_path = "/loggers/python/http-handler"
  easy_logs_token = "LIh982y87GgljahsadfklJHLIUG87g1u1e7f6eb2ee145571858e8e24"
  
  parsed_url = urlparse(easy_logs_host)
  
  #
  # CHANGE THIS: logging.handlers.HTTPHandler -> HTTPHandlerResilient
  #    
  http_handler = HTTPHandlerResilient(
    parsed_url.netloc,
    f'{easy_logs_path}?key={easy_logs_token}',
    method='POST',
    secure=True if parsed_url.scheme == "https" else False
  )
  logger.addHandler(http_handler)
  
  return logger
```

## Java (NOT IMPLEMENTED)

- [Log4j HTTP Appender](https://logging.apache.org/log4j/2.x/manual/appenders.html#HttpAppender)