IntersectMBO · Cmdv · Oct 29, 2025
@@ -1,8 +1,13 @@
+{-# LANGUAGE CPP #-}
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE NoImplicitPrelude #-}
 
 import Cardano.Db (MigrationDir (..), PGPassSource (PGPassDefaultEnv, PGPassEnv), gitRev)
 import Cardano.DbSync (runDbSyncNode)
+
+#ifdef GHC_DEBUG_ENABLED
+import GHC.Debug.Stub (withGhcDebug)
+#endif
 import Cardano.DbSync.Config
 import Cardano.DbSync.Config.Types
 import Cardano.DbSync.Metrics (withMetricSetters)
@@ -21,8 +26,16 @@ import Prelude (error)
 ---------------------------------------------------------------------------------------------------
 -- Main entry point into the app
 ---------------------------------------------------------------------------------------------------
+
 main :: IO ()
-main = do
+#ifdef GHC_DEBUG_ENABLED
+main = withGhcDebug dbSyncMain
+#else
+main = dbSyncMain
+#endif
+
+dbSyncMain :: IO ()
+dbSyncMain = do
   cmd <- Opt.execParser opts
   case cmd of
     CmdVersion -> runVersionCommand

@@ -17,6 +17,13 @@ build-type:             Custom
 extra-source-files:     CHANGELOG.md
                         schema/*.sql
 
+flag enable-ghc-debug
+  description: Enable ghc-debug profiling support for heap analysis.
+               Build with: cabal build --flag enable-ghc-debug cardano-db-sync
+               Zero overhead when disabled (production builds).
+  default: False
+  manual: True
+
 custom-setup
   setup-depends:
                         base
@@ -252,6 +259,12 @@ executable cardano-db-sync
                       , optparse-applicative
                       , text
 
+  if flag(enable-ghc-debug)
+    build-depends:      ghc-debug-stub
+    cpp-options:        -DGHC_DEBUG_ENABLED
+    ghc-options:        -finfo-table-map
+                        -fdistinct-constructor-tables
+
 executable http-get-json-metadata
   default-language:     Haskell2010
   main-is:              http-get-json-metadata.hs

@@ -0,0 +1 @@
+/tmp:5432:cexplorer:*:*
@@ -0,0 +1,110 @@
+# Cardano DB Sync - Developer Tools
+
+Local development tools for monitoring and profiling cardano-db-sync.
+
+## Overview
+
+Two complementary tools for understanding cardano-db-sync performance:
+
+### 🔍 [Monitoring](monitoring/README.md)
+Real-time metrics with Prometheus/Grafana
+- PostgreSQL metrics (queries, cache, connections)
+- System metrics (CPU, memory, disk I/O)
+- Time-series visualization
+
+### 🧠 [Profiling](profiling/README.md)
+Memory profiling with ghc-debug
+- Interactive heap exploration
+- Memory leak detection
+- Retainer chain analysis
+
+## Installation
+
+### Monitoring
+
+```bash
+# macOS
+brew install tmux prometheus postgres_exporter node_exporter grafana
+
+# Linux (apt)
+sudo apt-get install tmux prometheus postgres-exporter prometheus-node-exporter grafana
+
+# Linux (yum)
+sudo yum install tmux prometheus postgres_exporter node_exporter grafana
+```
+
+### Profiling
+
+```bash
+# Install ghc-debug-brick
+git clone https://gitlab.haskell.org/ghc/ghc-debug.git
+cd ghc-debug/brick
+cabal install ghc-debug-brick
+
+# Instrument cardano-db-sync (see profiling/README.md for details)
+```
+
+## Running
+
+### Start Monitoring
+
+```bash
+cd dev-tools/monitoring
+./scripts/start-monitoring.sh
+```
+
+Access at:
+- Prometheus: http://localhost:9090
+- Grafana: http://localhost:3000 (if started separately)
+
+### Start Profiling
+
+```bash
+cd dev-tools/profiling
+./scripts/start-profiling.sh
+
+# In another terminal (after several hours):
+ghc-debug-brick /tmp/cardano-db-sync.ghc-debug
+```
+
+### Run Both Together
+
+```bash
+# Terminal 1: Monitoring
+cd dev-tools/monitoring && ./scripts/start-monitoring.sh
+
+# Terminal 2: Profiling
+cd dev-tools/profiling && ./scripts/start-profiling.sh
+```
+
+## Directory Structure
+
+```
+dev-tools/
+├── README.md                   # This file
+│
+├── monitoring/                 # Prometheus/Grafana monitoring
+│   ├── README.md              # Full monitoring documentation
+│   ├── scripts/
+│   │   └── start-monitoring.sh
+│   ├── config/
+│   │   └── prometheus.yml
+│   ├── data/                  # Prometheus data (gitignored)
+│   └── docs/
+│       └── METRICS.md         # Available metrics
+│
+└── profiling/                 # ghc-debug profiling
+    ├── README.md              # Full profiling documentation
+    ├── scripts/
+    │   ├── start-profiling.sh
+    │   └── analyze-memory.sh
+    ├── snapshots/             # Heap snapshots (gitignored)
+    ├── logs/                  # Memory logs (gitignored)
+    └── reports/               # Analysis reports (commit these)
+```
+
+## Documentation
+
+- [Monitoring Setup Guide](monitoring/README.md)
+- [Profiling Setup Guide](profiling/README.md)
+- [Available Metrics Reference](monitoring/docs/METRICS.md)
@@ -0,0 +1,114 @@
+# Cardano DB Sync - Monitoring
+
+Local development monitoring using Prometheus and Grafana for PostgreSQL and system metrics.
+
+## Quick Setup
+
+### 1. Install Tools
+
+```bash
+# macOS
+brew install prometheus postgres_exporter node_exporter grafana
+
+# Linux (apt)
+sudo apt-get install prometheus postgres-exporter prometheus-node-exporter grafana
+
+# Linux (yum)
+sudo yum install prometheus postgres_exporter node_exporter grafana
+```
+
+### 2. Setup PostgreSQL Monitoring User
+
+```sql
+-- Connect to your database
+psql -U postgres -d cexplorer
+
+-- Create monitoring user
+CREATE USER postgres_exporter WITH PASSWORD 'secure_password';
+GRANT pg_monitor TO postgres_exporter;
+GRANT CONNECT ON DATABASE cexplorer TO postgres_exporter;
+```
+
+### 3. Start Monitoring
+
+```bash
+cd dev-tools/monitoring
+./scripts/start-monitoring.sh
+```
+
+This launches a tmux session with Prometheus and exporters.
+
+### 4. Start Grafana
+
+```bash
+# macOS
+brew services start grafana
+
+# Linux
+sudo systemctl start grafana-server
+```
+
+## Access Dashboards
+
+- **Prometheus**: http://localhost:9090
+- **Grafana**: http://localhost:3000 (default: admin/admin)
+
+## Grafana Setup
+
+1. Open http://localhost:3000
+2. Add Prometheus data source:
+   - Configuration → Data Sources → Add data source
+   - Select Prometheus
+   - URL: `http://localhost:9090`
+   - Save & Test
+3. Import dashboard:
+   - Dashboards → Import
+   - Upload `config/grafana-db-sync.json`
+   - Select Prometheus data source
+
+## Key Metrics
+
+- **System**: CPU, memory usage (node_exporter)
+- **PostgreSQL**: Connections, transaction rates, cache hit ratio
+- **Sync Progress**: Block height, epoch duration
+
+## Troubleshooting
+
+**postgres_exporter fails to connect**:
+- Verify monitoring user exists and has permissions
+- Set `DATA_SOURCE_NAME` with correct credentials in `scripts/start-monitoring.sh`
+
+**Prometheus shows "DOWN" targets**:
+- Check exporters are running: `ps aux | grep exporter`
+- Test endpoints: `curl http://localhost:9187/metrics` and `curl http://localhost:9100/metrics`
+
+**Port already in use**:
+```bash
+# Kill processes using ports
+lsof -ti:9090 | xargs kill  # Prometheus
+lsof -ti:9100 | xargs kill  # node_exporter
+lsof -ti:9187 | xargs kill  # postgres_exporter
+```
+
+## Stop Services
+
+```bash
+# Stop monitoring
+tmux kill-session -t cardano-monitoring
+
+# Stop Grafana
+brew services stop grafana           # macOS
+sudo systemctl stop grafana-server  # Linux
+```
+
+## Files
+
+- `scripts/start-monitoring.sh` - Launch monitoring suite
+- `config/prometheus.yml` - Prometheus configuration
+- `config/grafana-db-sync.json` - Grafana dashboard
+- `docs/METRICS.md` - Complete metrics reference
+
+## See Also
+
+- [Prometheus Documentation](https://prometheus.io/docs/)
+- [Grafana Documentation](https://grafana.com/docs/)