DOCSEARCHbyAlgolia
Submit Docs

ZinaLog Documentation

website·Indexed 31 days ago

https://zinalog.com

A lightweight, self-hosted logging and uptime monitoring server for centralized logs and uptime checks. Features include a REST HTTP API for log ingestion and data retrieval, a management dashboard, and a Node.js SDK (zinalog-node).

Tokens
7K
Snippets
26
Records
58
Agent score
49%

What's inside ZinaLog

  1. Overview of ZinaLog Core Principles and Architecture

    ZinaLog is a lightweight, self-hosted logging and uptime monitoring server designed as an alternative to complex observability stacks like ELK or Grafana. It is built on the following core principles:

    • Zero Infrastructure Overhead: Operates as a single process using an embedded SQLite database (utilizing Write-Ahead Logging/WAL mode for high-concurrency ingestion), eliminating the need for Redis, Postgres, or ElasticSearch.
    • Security: Includes built-in MFA, AES-256 encryption for sensitive settings, and API key management with IP restrictions.
    • Developer Experience: Provides a simple HTTP API for ingestion, a real-time 'Live Stream' dashboard, and instant alerting via Slack, Discord, Telegram, Email, and generic webhooks.

  2. Overview of ZinaLog capabilities

    ZinaLog is a lightweight, self-hosted logging and uptime monitoring server designed as a simpler alternative to full observability stacks like ELK or Grafana. It provides centralized logs, real-time visibility, and service checks. Key architectural advantages include zero infrastructure overhead (single process with embedded SQLite), high-concurrency ingestion via SQLite's Write-Ahead Logging (WAL) mode, and a small deployment footprint (Docker container < 100MB).

  3. Monitor real-time logs with the Overview Live Stream

    The Overview page provides a real-time Live Stream of logs using Server-Sent Events (SSE). New logs appear instantly without requiring a page refresh. Users can enable auto-scroll to keep the latest logs in view and click any log entry to view its full message and metadata.

  4. ZinaLog Technical Stack Overview

    ZinaLog is designed for performance, portability, and security in self-hosted deployments. Its core architecture consists of:

    • Frontend: Next.js with App Router (React Server Components).
    • Backend: Next.js API Routes (Node.js runtime).
    • Database: SQLite using sqlite3 and sqlite drivers.
    • UI: Tailwind CSS and Lucide React.
    • Key Features: Built-in async dispatchers for alerting, log fingerprinting for issue grouping, a background retention sweep (startup and hourly), and a monitoring scheduler for HTTP, TCP, and ping checks.

  5. Access Dashboard data and streaming APIs

    The following read-only endpoints are available to users with the viewer role or higher (requires valid session cookie):

    • GET /api/stats: Summary data for overview charts (counts by level, service distribution).
    • GET /api/errors: Error-level logs grouped by fingerprint (top 100 groups).
    • GET /api/services: List of all discovered service names.
    • GET /api/stream: A Server-Sent Events (SSE) stream of new logs. Includes a : heartbeat comment every 15 seconds.
    • GET /api/export: Exports logs in json (default) or csv (use format=csv) using the same filters as GET /api/logs.

  6. Search and filter historical logs

    The 'All Logs' section allows for deep historical analysis of ingested data. It supports full-text search across messages, service names, and metadata. Users can narrow results using filters for log level, service, or specific date ranges. Clicking a log entry opens a JSON view containing the complete payload, including stack traces and attached metadata.

  7. Install ZinaLog using the Quick Start CLI

    The fastest way to scaffold and run a local instance of ZinaLog is via the create-zinalog CLI tool. After running the installation, access the dashboard at http://localhost:4000 to complete the initial setup.
    npx create-zinalog my-logger
cd my-logger
npm run dev

  8. Configure service monitors and availability checks

    The Monitors page tracks service availability via three check types:

    • HTTP checks: Validates URLs with configurable methods, status ranges, headers, basic auth, redirects, SSL verification, timeouts, retries, and intervals. Also provides TLS certificate expiry and domain registration data.
    • TCP checks: Verifies if a specific host and port are reachable.
    • Ping checks: Tracks reachability for IP addresses or bare hostnames.

    Operators can trigger manual checks on demand to test a monitor before the next scheduled interval.

  9. Install ZinaLog manually via npm

    For manual installations, clone the repository, install dependencies, and configure the environment via a .env file in the project root. You can run the server in development mode or build it for production.
    git clone https://github.com/zinalog/zinalog.git
cd zinalog
npm install

    .env file

    PORT=4000 DATABASE_PATH=./data/logs.db ENCRYPTION_KEY=your-64-char-hex-key

    Start commands

    npm run dev # Development npm run build && npm start # Production

  10. Manage project announcements

    Project announcements (releases, security notices) are accessible via the bell icon in the sidebar. Users can dismiss announcements to hide them across all devices. Admins can disable all project notifications for the entire instance under Settings > General > Project Notifications.

  11. Deploy ZinaLog using Docker

    Docker is the recommended method for production deployments to ensure persistent storage. Use a docker-compose.yml file to define the service. To encrypt SMTP credentials, webhook URLs, and monitor secrets at rest, you must provide a 64-character hex ENCRYPTION_KEY in a .env file or shell environment.
    services:
  zinalog:
    image: ghcr.io/zinalog/zinalog:latest
    container_name: zinalog
    restart: unless-stopped
    ports:
      - "4000:4000"
    environment:
      PORT: "4000"
      HOSTNAME: "0.0.0.0"
      DATABASE_PATH: /data/logs.db
      TRUST_PROXY: "false" # Set to "true" if behind Nginx/Traefik
      ENCRYPTION_KEY: ${ENCRYPTION_KEY:-}
    volumes:
      - zinalog-data:/data

volumes:
  zinalog-data:
    # Run the container
docker compose up -d

# Generate a compatible encryption key
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

  12. Manage log grouping and issue triage

    ZinaLog groups logs of the same level (Errors, Warnings, Info, Debug) into 'issues' based on a computed fingerprint. The fingerprint ignores variable values (like UUIDs, emails, and timestamps) and includes the log level, service, and the first five application stack frames (skipping node_modules).

    Operators and admins can triage these issues using the following statuses:

    • Resolve: Marks the issue as fixed. If a matching log arrives later, it reopens as a 'regression' and triggers an alert.
    • Ignore: Hides the issue from the Open list and suppresses all associated alerts.
    • Reopen / Stop ignoring: Returns the issue to the Open status.