DOCSEARCHbyAlgolia
Submit Docs

Moonlogs Documentation

website·Indexed 30 days ago

https://moonlogs.pages.dev/

A specialized logging solution focused on capturing business events. Moonlogs features a built-in web interface, supports various DB adapters for data storage, and provides SDKs for TypeScript and Ruby on Rails.

Tokens
3K
Snippets
11
Records
23
Agent score
73%

What's inside Moonlogs

  1. Overview of Moonlogs business-event logging

    Moonlogs is a specialized logging solution focused on capturing business-event logs, such as user interactions, transactions, and custom application events. It is designed to provide transparency into complex business processes and is intended to complement (not replace) traditional knowledge bases, system logging, or Application Performance Monitoring (APM) tools. It includes a built-in web interface for searching and analyzing events.

  2. Use MongoDB for high-performance and scalable workloads

    MongoDB is recommended for the following scenarios:

    • High loads (hundreds of thousands to millions of requests per minute).
    • Strict latency requirements (average write response times of 5-15ms).
    • Requirement to horizontally scale the database across one or multiple servers.
    • High spikes in requests that significantly exceed average load (e.g., mass mailings, notifications, or SMS logging).

  3. Get started with Moonlogs

    To start submitting records (events) to Moonlogs, follow these four basic steps:

    1. Create an API token for authentication.
    2. Install a supported SDK (Ruby on Rails or Typescript) or use the REST API directly.
    3. Create domain schemas to act as containers for your records.
    4. Send records to the created schemas.

  4. Use SQLite for low to moderate workloads

    SQLite is the default adapter and is recommended for the following scenarios:

    • Low to moderate loads (0 to tens of thousands of requests per minute).
    • Average write response times of 60-90ms are acceptable.
    • No requirement for horizontal scaling across multiple servers.
    • Fast-paced logs with short retention periods (a few days).
    • No expected burst spikes reaching hundreds of thousands of requests per minute.

  5. Organize event schemas by business domains

    To facilitate efficient event retrieval and better categorization, create separate event schemas based on specific business domain areas. This ensures that events within each domain are recorded independently.

  6. Create a Moonlogs API token

    API tokens are required to authenticate requests to the Moonlogs API. To create one:

    1. Log into the Moonlogs Web interface.
    2. Navigate to the API token tab on the left sidebar.
    3. Click the plus (+) icon next to the API tokens header.
    4. Enter a name for the token and click Create.
    5. Copy the token immediately; it will not be displayed again.

  7. Install Moonlogs using Docker Compose

    Deploy Moonlogs using Docker Compose. This method requires Docker and Docker Compose to be installed. The configuration maps port 4200 and creates persistent volumes for configuration and data. After starting the container, access the UI at http://localhost:4200 to create the initial administrator account.
    version: '3'

services:
  moonlogs:
    image: pijng/moonlogs
    restart: always
    ports:
      - "4200:4200"
    volumes:
      - moonlogs-config:/etc/moonlogs
      - moonlogs-data:/var/lib/moonlogs
    command: --port=4200
volumes:
  moonlogs-config:
  moonlogs-data:
    # Build and run the Docker containers in detached mode
docker-compose up -d

  8. Choose a database adapter for Moonlogs

    Moonlogs does not store data internally; it uses database adapters for persistent storage. The choice of adapter depends on your load requirements, latency needs, and scaling strategy. Moonlogs currently supports two adapters: SQLite (default) and MongoDB.

  9. Install Moonlogs using the APT Repository

    Install Moonlogs on Linux systems by adding the official APT repository. Once installed, Moonlogs runs as a systemd service. After installation, access the UI at http://localhost:4200 to create the initial administrator account.
    # Add APT Repository
sudo add-apt-repository "deb [trusted=yes] https://apt.fury.io/pijng/ /"
sudo apt-get update

# Install moonlogs package
apt-get install moonlogs

# Check the status of the service
service moonlogs status

  10. Configure Moonlogs using config.yaml

    Moonlogs can be configured using a config.yaml file located by default at /etc/moonlogs/config.yaml. After modifying this file, the service must be restarted for changes to take effect.
    port: 4200
db_adapter: mongodb
db_path: 'mongodb://127.0.0.1:27017'
async_record_creation: false
read_timeout: 1s
write_timeout: 15s
    service moonlogs restart

  11. Moonlogs configuration options reference

    Moonlogs uses the following configuration options. If a value is unspecified, the default is used.
    port: 4200 # int: Port to listen for incoming connections
db_adapter: sqlite # sqlite | mongodb: Database driver to use
db_path: /var/lib/moonlogs/database.sqlite # string: Absolute path for SQLite or connection URL for MongoDB
read_timeout: 5s # duration: Max duration to wait for reading data from request
write_timeout: 1s # duration: Max duration to wait for writing data to client (also the Web UI response deadline)
async_record_creation: false # bool: Whether to create records asynchronously

  12. Enable asynchronous record creation

    Set async_record_creation to true to perform record creation operations asynchronously. This improves performance and prevents blocking code execution when sending logs if the client cannot handle async requests.

    Important: Asynchronous creation does not guarantee that logs will be stored in the order they were sent. To maintain consistent log ordering, it is highly recommended to provide a created_at parameter for your logs on the client side.