Electric SQL Monitoring with Vigilmon

Electric SQL is an open-source sync layer that sits in front of Postgres and enables local-first application architectures. It syncs data from Postgres to clients (browsers, mobile apps, edge functions) using a reactive shapes model — clients subscribe to a shape (a subset of Postgres data), and Electric pushes updates in real time. The result is applications that work offline and sync instantly when connectivity returns.

When Electric SQL is unavailable, clients can no longer sync data. Depending on your application design, users may still read stale local data, but any mutations they make offline cannot be committed until the sync layer is back. For applications that depend on real-time data consistency, Electric SQL downtime is a first-class incident.

This guide covers how to monitor Electric SQL with Vigilmon.

Electric SQL Architecture

Electric SQL runs as a stateless service (the Electric sync service) that connects to your Postgres database. In production you typically run:

• Electric sync service — the main process, connects to Postgres replication slot
• Postgres — the source of truth; Electric reads from a logical replication slot
• Optional: HTTP gateway / reverse proxy — exposes the Electric API to clients

The Electric sync service exposes an HTTP API that Vigilmon can monitor directly.

Electric SQL Health Endpoints

/api/health — Service Health

GET http://your-electric-host:3000/api/health

Response when healthy:

{
  "status": "active"
}

Response when Electric is not yet connected to Postgres or is in a degraded state:

{
  "status": "waiting"
}

The status field cycles through "waiting" (connecting), "active" (healthy), and "stopping" (shutting down). Monitor for "active" to confirm the sync service is fully operational.

/api/shapes/:shape_id — Shape API Availability

Electric clients subscribe to shapes via the HTTP API:

GET http://your-electric-host:3000/v1/shape?table=items

A successful response returns shape data with an electric-offset header. You can monitor this endpoint with a keyword check to confirm the shape API is serving data, not just that the process is running.

/metrics — Prometheus Metrics (Optional)

If you have Prometheus metrics enabled:

GET http://your-electric-host:3000/metrics

This endpoint exposes standard Prometheus metrics including connection counts, replication lag, and shape subscriber counts.

Setting Up Vigilmon Monitors

Monitor 1: Service Health (Primary)

1. Log in to Vigilmon → Monitors → New Monitor
2. Type: HTTP
3. Method: GET
4. URL: http://your-electric-host:3000/api/health
5. Interval: 1 minute
6. Expected status: 200
7. Keyword check: "status":"active"

This is your most important monitor. The "active" keyword check is critical — Electric returns HTTP 200 even in the "waiting" state, so a plain status check will not catch a service that is running but not yet connected to Postgres.

Monitor 2: Shape API Availability

Confirm that Electric is actively serving shape data to clients:

1. Type: HTTP
2. Method: GET
3. URL: http://your-electric-host:3000/v1/shape?table=your_table_name&offset=-1
4. Interval: 2 minutes
5. Expected status: 200

Replace your_table_name with a low-traffic table from your Postgres schema. The offset=-1 parameter requests a full initial sync, which is safe for monitoring since Electric will return the current shape snapshot.

Monitor 3: External Availability (via Proxy)

If you expose Electric behind a reverse proxy (Nginx, Caddy, Traefik):

1. Type: HTTP
2. Method: GET
3. URL: https://electric.your-domain.com/api/health
4. Interval: 1 minute
5. Expected status: 200
6. Keyword check: "status":"active"

The external monitor catches TLS certificate failures, proxy misconfigurations, and DNS issues that internal monitoring cannot detect.

Monitor 4: Postgres Connectivity Indicator

Electric's health endpoint directly reflects its Postgres connection state. If Postgres goes down or the replication slot is dropped, Electric will transition from "active" to "waiting". Your Monitor 1 (keyword "active") will therefore catch Postgres connectivity failures as well, without needing a separate Postgres monitor.

However, if your Postgres instance has its own monitoring endpoint (e.g., Neon, Supabase, or a managed provider), set up a separate monitor for it to distinguish between Electric service failures and upstream database failures.

Docker Compose Configuration

services:
  electric:
    image: electricsql/electric:latest
    environment:
      DATABASE_URL: postgresql://postgres:password@db:5432/myapp
      ELECTRIC_SECRET: your-secret
    ports:
      - "3000:3000"
    healthcheck:
      test:
        - "CMD"
        - "curl"
        - "-f"
        - "-s"
        - "http://localhost:3000/api/health"
        - "|"
        - "grep"
        - "active"
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 20s

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: password
    command:
      - postgres
      - -c
      - wal_level=logical

Note: Postgres must have wal_level=logical enabled. If this is not set, Electric will fail to create a replication slot and remain in the "waiting" state indefinitely — your Vigilmon monitor will catch this.

Kubernetes Deployment

livenessProbe:
  httpGet:
    path: /api/health
    port: 3000
  initialDelaySeconds: 30
  periodSeconds: 30
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /api/health
    port: 3000
  initialDelaySeconds: 10
  periodSeconds: 10
  failureThreshold: 5

The initialDelaySeconds: 30 gives Electric time to establish its Postgres replication connection before the readiness probe starts firing. Electric can take 10-30 seconds to initialize depending on database size and replication lag.

Alert Configuration

Slack Alerts

In Vigilmon → Alert Channels → Slack, configure an alert on the primary health monitor to fire after 1 failed check. Electric failures immediately prevent client sync, which users will notice within seconds in real-time applications.

Webhook Integration

app.post('/webhooks/vigilmon', express.json(), (req, res) => {
  const { event, monitor } = req.body;

  if (event === 'down') {
    console.error(`[Electric SQL] Sync service DOWN: ${monitor.url}`);
    // Users are now offline — trigger incident response
    createIncident({
      title: 'Electric SQL sync service unavailable',
      severity: 'critical',
      description: `Monitor: ${monitor.url} has been down since ${new Date().toISOString()}`,
    });
  } else if (event === 'up') {
    console.info(`[Electric SQL] Sync service RECOVERED`);
    resolveIncident({ source: 'electric-sql' });
  }

  res.json({ received: true });
});

Alerting Strategy

| Scenario | Monitor | Alert Threshold | |----------|---------|-----------------| | Sync service down | /api/health status non-200 | 1 failed check | | Not connected to Postgres | /api/health keyword "active" missing | 1 failed check | | Shape API unavailable | /v1/shape non-200 | 2 failed checks | | External availability | Proxy /api/health non-200 | 1 failed check | | High sync latency | /api/health > 3000ms | Warning alert |

Summary

| Component | Endpoint | Vigilmon Check | |-----------|----------|----------------| | Sync service health | /api/health | Status 200 + keyword "status":"active" | | Shape API | /v1/shape?table=X&offset=-1 | Status 200 | | External availability | Proxy /api/health | Status 200 + keyword "active" | | Postgres connectivity | Inferred from /api/health keyword | "status":"active" |

Electric SQL's "waiting" vs "active" distinction makes keyword monitoring essential — a status check alone will not tell you whether your sync layer is actually syncing. With Vigilmon's keyword monitors and 1-minute intervals, you will know the moment Electric loses its Postgres connection or falls behind on replication.

Further Reading

• Monitoring Neon Postgres with Vigilmon
• Monitoring Supabase with Vigilmon
• Monitoring Hasura GraphQL Engine with Vigilmon
• Docker Container Monitoring with Vigilmon