Monitoring & Grafana Dashboards

Status Page

OpenPay includes a built-in status page at /status that provides real-time health monitoring of all core services. The page auto-refreshes every 30 seconds.

How It Works

The status page uses a server-side API route (/api/health) to check each service. This avoids CORS issues that would occur with direct browser-to-service requests.

Browser → /api/health → Server → Service endpoints
                          ↓
                   Returns JSON with status + latency
                          ↓
                   Browser displays Operational/Down

Monitored Services

Accessing the Status Page

# Local development
open http://localhost:3000/status

# Production (via Docker)
open http://your-domain.com/status

Customizing Health Check URLs

Health check URLs are configurable via environment variables. Set these in your .env file to point to your actual service addresses:

# Status Page Health Check URLs
# Defaults work for local Docker development
HEALTH_CHECK_HYPERSWITCH_URL=http://localhost:8081/health
HEALTH_CHECK_KILLBILL_URL=http://localhost:8082/1.0/healthcheck
HEALTH_CHECK_NATS_URL=http://localhost:8222/healthz
HEALTH_CHECK_TAZAMA_URL=http://localhost:8084/health

# Production example (Docker internal network):
HEALTH_CHECK_HYPERSWITCH_URL=http://hyperswitch:8080/health
HEALTH_CHECK_KILLBILL_URL=http://killbill:8080/1.0/healthcheck
HEALTH_CHECK_NATS_URL=http://nats:8222/healthz
HEALTH_CHECK_TAZAMA_URL=http://tazama-rule-exec:8080/health

What's In the Stack

Step 1 — Start the Monitoring Stack

docker compose --profile monitoring up -d

# Verify all four are healthy
docker compose ps prometheus grafana loki promtail

Log in to Grafana at http://localhost:3000 with admin / admin (or the GRAFANA_ADMIN_PASSWORD from your root .env). You'll be asked to set a new password on first login.

Step 2 — Dashboards That Ship With the App

The repo provisions dashboards automatically from monitoring/grafana/dashboards/dashboards/. The Prometheus data source and the OpenPay Overview dashboard are loaded at container start (no manual import needed):

• OpenPay Overview — service up/down status for Hyperswitch, Kill Bill, and the total up count.

Step 3 — The File Format (What a Dashboard Actually Is)

A Grafana dashboard is a single JSON file — nothing more. The main blocks are:

• title & uid — dashboard name and unique ID
• panels[] — each panel is one visualization (stat, time series, bar gauge…)
• panels[].targets[] — the PromQL queries powering each panel
• templating — optional dropdown variables (e.g. pick a service)
• time — the default time range

{
  "title": "My Dashboard",
  "uid": "my-dashboard",
  "panels": [
    {
      "type": "stat",
      "title": "Hyperswitch Up?",
      "targets": [
        { "expr": "up{job="hyperswitch"}", "legendFormat": "Hyperswitch" }
      ]
    }
  ],
  "time": { "from": "now-6h", "to": "now" }
}

Step 4 — Create a Dashboard (Three Ways)

# 1. Place your exported JSON here:
#    monitoring/grafana/dashboards/dashboards/my-dashboard.json

# 2. Reload (picks up within 30s, or force it):
docker compose restart grafana

Step 5 — Explore Logs

Promtail ships every Docker container's logs to Loki. In Grafana open Explore, switch the data source to Loki, and query e.g. {service="hyperswitch"} or use the Log labels dropdown to pick a container.

{service="hyperswitch"}          # all Hyperswitch logs
{service="killbill"} |~ "error"  # Kill Bill errors only
{container="core-hyperswitch"}

Troubleshooting

• Dashboards don't appear: ensure the four monitoring containers are healthy (docker compose ps), then restart Grafana.
• Panels show “No data”: the target service may not expose Prometheus metrics, or the scrape target is unreachable. Check http://localhost:9090/targets for scrape errors.
• No logs in Loki: confirm the Docker socket is mounted to promtail (already in docker-compose.yml) and check docker compose logs promtail.