gcsboss/logman repository overview

⁠Logman⁠

Logman is a lightweight, standalone observer for your Docker stack. It sits alongside your containers, watches their logs in real-time, and provides smart error alerting and a simple web dashboard.

Built in Rust for blazing speed and minimal footprint.

⁠Features

• Zero-Config Injection: Just mount the Docker socket. Logman auto-discovers running containers and starts watching immediately.
• Smart Alerting: No more email floods. Logman uses exponential backoff and "first-seen/last-seen" logic to group identical errors.
  • Example: If a DB connection fails 1,000 times in a minute, you get one alert, not 1,000.
• Email Notifications: Built-in SMTP client to send clean, HTML-formatted alerts for critical issues.
• Real-time Dashboard: A lightweight web UI to view active error clusters, frequencies, and recent stack traces.
• Redis Pub/Sub: Streams processed logs to a Redis channel, letting you hook in other tools or custom scripts easily.
• Docker Native: Aware of Docker Compose stacks, service names, and node metadata.

⁠Quick Start

Add logman to your docker-compose.yml. It requires access to a Redis instance (for state tracking) and the Docker Socket (to read logs).

services:
  # Your Application
  api:
    image: my-api:latest

  # Logman Observer
  logman:
    image: gcsboss/logman:latest
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro # Read-only access is enough
    environment:
      - REDIS_URL=redis://redis:6379/
      - SMTP_HOST=smtp.mailgun.org
      - SMTP_PORT=587
      - [email protected]
      - SMTP_PASS=secret-password
      - [email protected]
      - [email protected]
    ports:
      - "3000:3000" # Web Dashboard
    depends_on:
      - redis

  redis:
    image: redis:7-alpine

⁠🖥️ Access the Dashboard

Once running, open your browser to http://localhost:3000. You will see a live list of aggregated errors, their counts, and their most recent occurrences.

⁠⚙️ Configuration

Logman is configured entirely via Environment Variables.

⁠📝 Log Formatting

Logman works best when your applications output JSON logs. It automatically parses them to extract levels and metadata.

⁠Recommended Format (JSON)

If your app logs in JSON, Logman looks for these fields:

• level: "debug", "info", "warn", "error", or "fatal".
• msg or message: The actual log text.
• errorId: (Optional) A unique code for the error type (e.g., PAYMENT_GATEWAY_TIMEOUT). Highly Recommended for accurate grouping.

Example:

{"level": "error", "time": 1678888, "msg": "Database connection failed", "errorId": "DB_CONN_ERR", "retry": 3}

⁠Fallback Format (Plain Text)

If your app logs plain text, Logman treats the entire line as the message and defaults the level to INFO.

• Note: Alerts generally only trigger on ERROR or FATAL levels, so plain text logs might not trigger emails unless you parse them in your app first.

⁠How Alerting Works

Logman implements a Smart Backoff strategy to prevent alert fatigue.

1. Grouping: Errors are grouped by their errorId. If no errorId is present, they may not be grouped effectively.
2. Counting: Every occurrence is counted in Redis.
3. Triggering: Emails are sent ONLY when the occurrence count hits specific Powers of 4 (1, 4, 16, 64, 256...).
4. Reset: If an error stops happening for a certain period (depending on severity), the counter resets.

This ensures you know immediately when an error starts, get updates if it persists, but don't get 5,000 emails for a tight loop failure.