mohammedaljer/n8n-trace repository overview

⁠mohammedaljer/n8n-trace

Self-hosted observability dashboard for n8n. Tracks workflow executions, instance health metrics, and provides a Prometheus-style metrics explorer — all behind role-based access control with audit logging. Runs as a single Docker container backed by PostgreSQL. Push-based ingestion; n8n-trace never calls your n8n instances.

⁠Architecture

n8n-trace uses a push-based ingestion model. Scheduled workflows running inside your n8n instances collect execution data and metrics and write them directly to PostgreSQL. The n8n-trace service reads from the database and presents analytics in the dashboard.

n8n Instance
     │
     │ (scheduled workflows)
     ▼
PostgreSQL  ◄── n8n-trace
     │
     ▼
Dashboard (React)

⁠Key Features

• Drop-in deployment — single container serves the React SPA and Express API; no NGINX required
• Execution analytics — success/failure rates, duration trends, node-level performance breakdown
• Instance monitoring — CPU, memory, event loop metrics from n8n's Prometheus endpoint
• Metrics Explorer — query and chart any Prometheus-style metric with label filtering, aggregation, and time ranges
• Multi-instance support — monitor production, staging, and development n8n instances from one dashboard
• RBAC — Admin / Analyst / Viewer roles with instance, workflow, and tag scoping
• Audit logging — all security events logged with configurable IP privacy (raw, hashed, none)
• Push-based ingestion — n8n workflows write to PostgreSQL; zero outbound connections from n8n-trace
• Auto-migrations — database schema upgrades run automatically on startup via node-pg-migrate
• Distroless runtime — Google Distroless base image (no shell, non-root, minimal attack surface)

⁠Tags

⁠Quick Start

docker run -d \
  --name n8n-trace \
  -p 8899:8001 \
  -e APP_ENV=production \
  -e DATABASE_URL=postgres://n8n_trace:password@host:5432/n8n_trace \
  -e JWT_SECRET=your-secret-minimum-32-characters \
  -e APP_URL=http://localhost:8899 \
  -e CORS_ORIGIN=http://localhost:8899 \
  mohammedaljer/n8n-trace:latest

The dashboard will be available at http://localhost:8899.

⁠Docker Compose (Recommended)

services:
  postgres:
    image: postgres:17.2-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: n8n_trace
      POSTGRES_USER: n8n_trace
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?required}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U n8n_trace -d n8n_trace"]
      interval: 5s
      timeout: 5s
      retries: 10
    security_opt:
      - no-new-privileges:true

  app:
    image: mohammedaljer/n8n-trace:v2.0.0
    container_name: n8n_trace_app
    restart: unless-stopped
    ports:
      - "${HTTP_PORT:-8899}:8001"
    environment:
      APP_ENV: production
      DATABASE_URL: postgres://n8n_trace:${POSTGRES_PASSWORD}@postgres:5432/n8n_trace
      PORT: "8001"
      JWT_SECRET: ${JWT_SECRET:?required - minimum 32 characters}
      APP_URL: ${APP_URL:-http://localhost:8899}
      CORS_ORIGIN: ${CORS_ORIGIN:-http://localhost:8899}
      COOKIE_SECURE: ${COOKIE_SECURE:-true}
      TRUST_PROXY: ${TRUST_PROXY:-false}
      RETENTION_ENABLED: ${RETENTION_ENABLED:-true}
      RETENTION_DAYS: ${RETENTION_DAYS:-90}
      METRICS_ENABLED: ${METRICS_ENABLED:-true}
    depends_on:
      postgres:
        condition: service_healthy
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp:noexec,nosuid,size=64M
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "1.0"

volumes:
  postgres_data:

Create a .env file with your secrets:

POSTGRES_PASSWORD=your-strong-database-password
JWT_SECRET=your-jwt-secret-minimum-32-characters
APP_URL=https://trace.yourdomain.com
CORS_ORIGIN=https://trace.yourdomain.com

⁠Configuration

⁠Application

⁠Data & Metrics

⁠Security & Account

⁠Data Ingestion

n8n-trace uses a push-based model. Two n8n workflows (included in the repository under Workflows/) run on a schedule inside your n8n instance:

1. Execution Collector — collects execution data and workflow metadata
2. Metrics Snapshot — captures instance health metrics from n8n's /metrics endpoint

Both write directly to PostgreSQL using a least-privilege ingest user that has INSERT/UPDATE access to ingestion tables only — no access to user accounts, audit logs, or RBAC configuration.

See the Workflows README⁠ for setup instructions.

⁠Security

⁠Container Hardening

• Distroless base image — gcr.io/distroless/nodejs22-debian12:nonroot (no shell, no package manager)
• Non-root execution — runs as UID 65534
• Read-only filesystem — read_only: true with tmpfs /tmp
• No new privileges — no-new-privileges security opt
• Resource limits — 512 MB memory, 1 CPU

⁠Application Security

• Strict CSP — all Content Security Policy directives locked to 'self'
• HttpOnly/Secure/SameSite cookies — JWT tokens never accessible to JavaScript
• Account lockout — configurable threshold with timing-safe responses
• CSRF protection — Origin/Referer validation on all mutating API endpoints
• Password policy — 12-char minimum with common-password denylist
• Fail-fast startup — refuses to start in production with weak secrets or insecure configuration

⁠Recommendations

• Do not expose n8n-trace directly to the internet. Use a reverse proxy (nginx, Traefik, Caddy) with TLS termination.
• Use Docker secrets or .env files for credentials. Never commit secrets to version control.
• Set N8N_DIAGNOSTICS_ENABLED=false on your n8n instances if you prefer not to send anonymous usage data.

⁠Upgrades

1. Pin to a specific version tag in production (e.g., v2.0.0)
2. Read the CHANGELOG⁠ before upgrading
3. Back up your PostgreSQL database before pulling a new tag
4. Database migrations run automatically on startup — no manual steps required

⁠Health Checks

The Docker Compose examples include a built-in healthcheck using node fetch() (no curl required in distroless).

⁠License & Credits

• n8n — n8n.io⁠ is the upstream workflow automation platform. n8n-trace is an independent observability layer; it does not modify or redistribute n8n.
• Built with Express.js, React 18, PostgreSQL, and node-pg-migrate⁠.

This project is licensed under the MIT License⁠.