The monitoring bundle is activated with a single environment variable:

MONITORING_ENABLED=true

This automatically enables 10 monitoring services with smart dependency handling.

• Purpose: Time-series database for metrics
• What it does: Scrapes and stores metrics from all services
• Port: 9090 (default)
• Always needed?: ✅ YES - Core of monitoring stack
• Dependencies: None
• Scrapes metrics from:
  • Itself (prometheus:9090)
  • Node Exporter (system metrics)
  • cAdvisor (container metrics)
  • Postgres Exporter (database metrics)
  • Redis Exporter (Redis metrics)
  • Hasura (application metrics)
  • Custom services (if configured)

• Purpose: Create dashboards and visualize metrics/logs
• What it does: Provides UI for viewing Prometheus metrics and Loki logs
• Port: 3000 (default)
• Always needed?: ⚠️ RECOMMENDED - Without it, you can't see the data visually
• Dependencies: Prometheus (for metrics), Loki (for logs)
• Access: https://grafana.local.nself.org
• Default credentials: admin/admin (change via GRAFANA_ADMIN_PASSWORD)

• Purpose: Collect and query logs from all containers
• What it does: Stores logs in a queryable format
• Port: 3100 (default)
• Always needed?: ⚠️ RECOMMENDED - Logs are critical for debugging
• Dependencies: None (but needs Promtail to ship logs to it)
• Similar to: Elasticsearch, but more lightweight

• Purpose: Ships logs from Docker containers to Loki
• What it does: Reads Docker container logs and forwards to Loki
• Port: 9080 (internal only)
• Always needed?: ✅ YES if using Loki - Without it, Loki receives no logs
• Dependencies: Loki (must be running)
• Critical: This is the connector between containers and Loki

• Purpose: Track requests across multiple services
• What it does: Stores and queries distributed traces (like Jaeger)
• Ports: 3200 (HTTP), 14268 (Jaeger ingest)
• Always needed?: ❌ NO - Only if you're doing distributed tracing
• Dependencies: None
• Use case: Track a request from frontend → API → database → external service
• Optional: Can disable with TEMPO_ENABLED=false

• Purpose: Route and manage alerts from Prometheus
• What it does:
  • Receives alerts from Prometheus
  • Groups, deduplicates, silences alerts
  • Routes to notification channels (email, Slack, PagerDuty)
• Port: 9093 (default)
• Always needed?: ❌ NO - Only if you want alerting
• Dependencies: Prometheus (sends alerts to it)
• Use case: Get notified when CPU > 90%, disk full, service down
• Optional: Can disable with ALERTMANAGER_ENABLED=false

• Purpose: Expose Docker container metrics to Prometheus
• What it does:
  • Monitors CPU, memory, disk, network usage per container
  • Provides /metrics endpoint for Prometheus
• Port: 8082 (default)
• Always needed?: ✅ YES for container monitoring
• Dependencies: Docker daemon
• Metrics exposed: Container CPU, memory, disk I/O, network
• OS-aware: Adjusts volume mounts for macOS vs Linux

• Purpose: Expose host system metrics to Prometheus
• What it does:
  • Monitors CPU, memory, disk, network at the host level
  • Shows overall system health
• Port: 9100 (default)
• Always needed?: ✅ YES for system monitoring
• Dependencies: None
• Metrics exposed: System CPU, memory, disk usage, file descriptors, network

• Purpose: Expose PostgreSQL database metrics to Prometheus
• What it does:
  • Monitors database connections, queries, locks, table sizes
  • Tracks slow queries, replication lag
• Port: 9187 (default)
• Always needed?: ✅ YES - PostgreSQL is always required in nself
• Dependencies: PostgreSQL service (always present as required service)
• Note: Since PostgreSQL is a required service, this exporter is always included in the monitoring bundle

• Purpose: Expose Redis metrics to Prometheus
• What it does:
  • Monitors Redis memory, connections, hit rate, key count
  • Tracks command stats, replication
• Port: 9121 (default)
• Always needed?: ⚠️ CONDITIONAL - Only if Redis is enabled
• Dependencies: Redis service (REDIS_ENABLED=true)
• Smart logic: Automatically disabled if Redis not enabled

When you set MONITORING_ENABLED=true, the system:

1. Enables all 10 services with smart defaults
2. Checks dependencies before starting each exporter
3. Auto-disables Redis Exporter if Redis isn't enabled

# In monitoring-exporters.sh

# Postgres Exporter - Always included (PostgreSQL is required)
[[ "${POSTGRES_EXPORTER_ENABLED:-false}" != "true" ]] && return 0
# Note: No POSTGRES_ENABLED check - PostgreSQL is always present

# Redis Exporter - Only if Redis is enabled
[[ "${REDIS_EXPORTER_ENABLED:-false}" != "true" ]] && return 0
[[ "${REDIS_ENABLED:-false}" != "true" ]] && return 0     # ← Smart check!

This means:

• ✅ Postgres Exporter is always included (PostgreSQL is a required service)
• ⚠️ Redis Exporter is only included if Redis is enabled

MONITORING_ENABLED=true
# No Redis, no MinIO, no other optional services

Result:

• ✅ Prometheus, Grafana, Loki, Promtail (4)
• ✅ Tempo, Alertmanager (2)
• ✅ cAdvisor, Node Exporter, Postgres Exporter (3)
• ❌ Redis Exporter (0) - Redis not enabled
• Total: 9 containers (full monitoring except Redis Exporter)

REDIS_ENABLED=true
MINIO_ENABLED=true
# ... other optional services
MONITORING_ENABLED=true

Result:

• ✅ All 10 monitoring services
• ✅ Postgres Exporter (PostgreSQL present)
• ✅ Redis Exporter (Redis present)
• Total: 10 containers (full monitoring stack)

# .env
MONITORING_ENABLED=true

This enables everything with sensible defaults.

# .env
MONITORING_ENABLED=true

# Optionally disable specific services
TEMPO_ENABLED=false           # Don't need tracing
ALERTMANAGER_ENABLED=false    # Don't need alerting yet

# Customize ports
GRAFANA_PORT=3001
PROMETHEUS_PORT=9091

# Customize Grafana
GRAFANA_ADMIN_PASSWORD=mysecretpassword

# .env
# Don't set MONITORING_ENABLED=true

# Enable only what you need
PROMETHEUS_ENABLED=true
GRAFANA_ENABLED=true
NODE_EXPORTER_ENABLED=true
CADVISOR_ENABLED=true

1. ✅ Prometheus - Core metrics database
2. ✅ Grafana - Visualization (technically optional, but you want this)
3. ✅ cAdvisor - Container metrics
4. ✅ Node Exporter - System metrics

5. ✅ Postgres Exporter - Always included (PostgreSQL is required)
6. ⚠️ Redis Exporter - Only if Redis enabled

7. ✅ Loki - Log storage
8. ✅ Promtail - Log shipping (required for Loki to work)

9. ❌ Tempo - Only for distributed tracing
10. ❌ Alertmanager - Only for alerting

• Prometheus, Grafana, cAdvisor, Node Exporter
• Memory: ~500MB
• Good for: Development

• Above + Loki, Promtail, Postgres Exporter, Redis Exporter
• Memory: ~1GB
• Good for: Staging

• All services including Tempo and Alertmanager
• Memory: ~1.2GB
• Good for: Production

When MONITORING_ENABLED=true, Prometheus automatically scrapes:

# monitoring/prometheus/prometheus.yml (auto-generated)
scrape_configs:
  - job_name: 'prometheus'        # Itself
  - job_name: 'node'              # Node Exporter
  - job_name: 'cadvisor'          # cAdvisor
  - job_name: 'postgres'          # Postgres Exporter
  - job_name: 'redis'             # Redis Exporter
  - job_name: 'hasura'            # Hasura GraphQL
  - job_name: 'custom_*'          # Custom services (auto-added)

Important: The config is smart - it includes targets even if they're not running. Prometheus will show them as "DOWN" which is useful for debugging.

MONITORING_ENABLED=false

Or enable minimal:

PROMETHEUS_ENABLED=true
GRAFANA_ENABLED=true

MONITORING_ENABLED=true
TEMPO_ENABLED=false          # Skip tracing
ALERTMANAGER_ENABLED=false   # Skip alerting

MONITORING_ENABLED=true
# Enable everything!
GRAFANA_ADMIN_PASSWORD=strong-password

When monitoring is enabled:

Exporters don't have public URLs - they're internal services scraped by Prometheus.

A: No. You need at minimum:

• Prometheus (metrics)
• Grafana (visualization)
• cAdvisor (container metrics)
• Node Exporter (system metrics)

A: Redis Exporter won't start. The system detects Redis isn't enabled and skips it. No errors, no wasted resources.

A: Yes! Just add MONITORING_ENABLED=true to your .env and run nself build --force && nself start

A: Minimal. Exporters use <50MB each. Prometheus/Grafana are the heaviest (~200-300MB each).

A: Yes. Even with MONITORING_ENABLED=true, you can set:

TEMPO_ENABLED=false
ALERTMANAGER_ENABLED=false

A: Run nself build --force to regenerate config, then nself start. Redis Exporter will be added automatically.

if [[ "$MONITORING_ENABLED" == "true" ]]; then
  export PROMETHEUS_ENABLED="${PROMETHEUS_ENABLED:-true}"
  export GRAFANA_ENABLED="${GRAFANA_ENABLED:-true}"
  export LOKI_ENABLED="${LOKI_ENABLED:-true}"
  export PROMTAIL_ENABLED="${PROMTAIL_ENABLED:-true}"
  export TEMPO_ENABLED="${TEMPO_ENABLED:-true}"
  export ALERTMANAGER_ENABLED="${ALERTMANAGER_ENABLED:-true}"
  export CADVISOR_ENABLED="${CADVISOR_ENABLED:-true}"
  export NODE_EXPORTER_ENABLED="${NODE_EXPORTER_ENABLED:-true}"
  export POSTGRES_EXPORTER_ENABLED="${POSTGRES_EXPORTER_ENABLED:-true}"
  export REDIS_EXPORTER_ENABLED="${REDIS_EXPORTER_ENABLED:-true}"
fi

# Postgres Exporter - Always included (PostgreSQL is required)
generate_postgres_exporter_service() {
  [[ "${POSTGRES_EXPORTER_ENABLED:-false}" != "true" ]] && return 0
  # Note: No POSTGRES_ENABLED check - PostgreSQL is always present
  # ... generate service
}

# Redis Exporter - Only if Redis is enabled
generate_redis_exporter_service() {
  [[ "${REDIS_EXPORTER_ENABLED:-false}" != "true" ]] && return 0
  [[ "${REDIS_ENABLED:-false}" != "true" ]] && return 0     # ← Smart check!
  # ... generate service
}

✅ Single variable: MONITORING_ENABLED=true ✅ 10 services: 4 core + 2 logging + 1 tracing + 1 alerting + 2 exporters (conditional) ✅ Smart dependencies: Exporters only start if their target service exists ✅ Zero configuration: Works out of the box with sensible defaults ✅ Fully customizable: Override any setting as needed

The system is smart enough to handle dependencies automatically. You don't need to worry about enabling/disabling exporters based on optional services - it's handled for you!

Summary:

• 9 services always included when MONITORING_ENABLED=true (without Redis)
• 10 services included when Redis is also enabled
• PostgreSQL is a required service, so its exporter is always included
• Only Redis Exporter has conditional logic based on optional service

✅ PostgreSQL is always required → Postgres Exporter always included ⚠️ Redis is optional → Redis Exporter only included if Redis enabled

The system handles this automatically - you don't need to manually configure anything!