Monitoring Your Instance

Catch indexing lag and outages before your users do.

A self-hosted explorer has three things worth watching: the API server, the indexer’s progress, and the database. This page covers health endpoints, metrics, and a minimal alerting setup.

Health checks

Indexing status (most important)

curl http://localhost:4000/api/v2/main-page/indexing-status

{
  "finished_indexing": true,
  "finished_indexing_blocks": true,
  "indexed_blocks_ratio": "1.0",
  "indexed_internal_transactions_ratio": "1.0"
}

Alert when indexed_blocks_ratio drops below ~0.99 while the chain is producing blocks — the indexer is falling behind.

API liveness

curl -f http://localhost:4000/api/v2/stats

Any non-200 response means the API server needs attention.

Database

Standard PostgreSQL monitoring applies: connection count, disk usage, replication lag (if replicated), and slow queries. Disk usage is the one that bites explorers — indexed data grows continuously.

Metrics

The backend exposes Prometheus-compatible metrics. Scrape them and graph:

Indexer block import rate — should track the chain’s block time.
Fetcher queue depths — rising queues mean the RPC endpoint or database can’t keep up.
HTTP request rate and latency — for capacity planning.

A Grafana dashboard with “blocks indexed per minute,” “queue depth by fetcher,” and “API p95 latency” covers 95% of operational questions.

Log-based alerting

Backend logs are structured and tagged by module. Useful alert rules:

Log pattern	Meaning
Repeated JSON-RPC errors from one fetcher	RPC endpoint rate-limited or unreachable
`reorg` appearing frequently	Chain instability or an unsuitable RPC node
Database connection errors	Postgres down or connection pool exhausted
Disk space warnings	Expand the volume immediately

Ship container logs to your usual stack (Loki, ELK, CloudWatch) with docker compose logs or a logging driver.

External uptime monitoring

Point an external probe (UptimeRobot, Better Stack, your status page system) at https://your-explorer/api/v2/stats. Internal-only monitoring can’t tell you when the whole host is down.

Alerting thresholds that work

Indexing ratio < 0.99 for 10 minutes — investigate RPC/database.
Disk usage > 80% — expand or prune; > 90% is an emergency.
API 5xx rate > 1% for 5 minutes — check backend and database.
Container restarts > 3 in 10 minutes — crash loop; read the logs.

During chain upgrades

When the chain you index schedules a hard fork or coordinated upgrade, expect RPC instability. The indexer tolerates node restarts; just watch the indexing ratio afterward and confirm it recovers to ~1.0.