Monitoring

WaSphere exposes health endpoints, structured JSON logs, and Docker health checks to integrate with your existing monitoring stack. This page covers built-in observability tools and how to set up alerting.

Health Endpoints

Dashboard API — /health

A lightweight liveness probe. It returns 200 with a minimal body whenever the API process is up — ideal for uptime monitors and load-balancer checks.

curl https://api.yourdomain.com/health

{ "status": "ok" }

WA Server — /health

The WA Server health endpoint is richer: it reports version, uptime, memory, and the live status of every WhatsApp session. It listens on port 3001 and is normally only reachable inside the Docker network:

docker compose exec wa-server wget -qO- http://localhost:3001/health

{
  "status": "ok",
  "version": "1.0.0",
  "uptime": 86400,
  "timestamp": "2026-05-25T10:00:00.000Z",
  "memory": { "rss": 257425408, "heapUsed": 142336000 },
  "whatsapp": {
    "totalSessions": 3,
    "connectedSessions": 2,
    "sessions": [
      { "id": "support", "status": "connected" },
      { "id": "sales", "status": "connected" },
      { "id": "notifications", "status": "reconnecting" }
    ]
  }
}

Two extra probes are available for orchestrators (Kubernetes, etc.):

• GET /health/live — always returns 200 {"status":"ok"} while the process runs (liveness)
• GET /health/ready — returns 200 only when at least one session is connected, otherwise 503 (readiness)

Session status via the API

Get live status for all sessions through the Dashboard API with a scoped key:

curl https://api.yourdomain.com/workspaces/{workspaceId}/proxy/api/sessions \
  -H "Authorization: Bearer wsk_your_key"

Docker Health Checks

The docker-compose.yml configures health checks for all services. View current health:

docker compose ps
docker inspect --format='{{.Name}}: {{.State.Health.Status}}' $(docker compose ps -q)

Example output:

/wasphere-postgres-1: healthy
/wasphere-wa-server-1: healthy
/wasphere-dashboard-api-1: healthy
/wasphere-dashboard-ui-1: healthy

Health check configuration (reference)

# From docker-compose.yml
services:
  dashboard-api:
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:3000/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

  wa-server:
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:3001/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s

  postgres:
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U wasphere -d wasphere"]
      interval: 10s
      timeout: 5s
      retries: 5

Log Management

Log format

All WaSphere services output structured JSON logs to stdout:

{
  "level": "info",
  "message": "Message sent successfully",
  "sessionId": "sess_abc123",
  "messageId": "3EB0C767D097B7C7A5C1",
  "to": "447700900456",
  "durationMs": 145,
  "timestamp": "2026-05-25T10:00:00.000Z"
}

Log levels

Set LOG_LEVEL in .env to control verbosity:

Viewing logs

# All services
docker compose logs -f

# Specific service, last 100 lines
docker compose logs wa-server --tail=100 -f

# Filter for errors only (requires jq)
docker compose logs dashboard-api -f | jq 'select(.level == "error")'

# Search for a specific session
docker compose logs wa-server -f | grep "sess_abc123"

Shipping logs to a log aggregator

services:
  dashboard-api:
    logging:
      driver: loki
      options:
        loki-url: "http://loki:3100/loki/api/v1/push"
        loki-batch-size: "400"
        labels: "service,version"

docker plugin install grafana/loki-docker-driver:latest --alias loki --grant-all-permissions

services:
  dashboard-api:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
    labels:
      com.datadoghq.ad.logs: '[{"source": "nodejs", "service": "wasphere-api"}]'

  datadog:
    image: gcr.io/datadoghq/agent:7
    environment:
      DD_API_KEY: ${DD_API_KEY}
      DD_LOGS_ENABLED: "true"
      DD_LOGS_CONFIG_CONTAINER_COLLECT_ALL: "true"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /proc/:/host/proc/:ro

services:
  dashboard-api:
    logging:
      driver: syslog
      options:
        syslog-address: "udp://logs.papertrailapp.com:PORT"
        tag: "wasphere-api"

Uptime Monitoring

Use an external uptime monitor (Better Uptime, UptimeRobot, Freshping, etc.) to alert you when the health endpoint goes down.

Endpoint to monitor: https://api.yourdomain.com/health Expected HTTP status: 200 Check interval: 1–5 minutes Alert threshold: 2 consecutive failures (avoids false positives from brief blips)

Example: UptimeRobot configuration

1. Create a new monitor — HTTPS type
2. URL: https://api.yourdomain.com/health
3. Monitoring interval: 5 minutes
4. Alert contacts: your email/Slack
5. Keyword check: "status":"ok" (string match in response body for deeper health validation)

Alerting on Session Disconnects

Beyond infrastructure monitoring, you'll want alerts when a WhatsApp session drops. Use WaSphere webhooks for this:

// Express.js webhook handler — alert on session disconnect
app.post('/webhooks/wasphere', verifySignature, (req, res) => {
  res.json({ received: true });

  const { event, data } = req.body;
  
  if (event === 'session.disconnected') {
    const { sessionName, reason } = data;
    
    // Send alert via your preferred channel
    sendSlackAlert({
      text: `WhatsApp session disconnected`,
      blocks: [
        {
          type: 'section',
          text: {
            type: 'mrkdwn',
            text: `*Session:* ${sessionName}\n*Reason:* ${reason}\n*Action needed:* Check the WaSphere dashboard`
          }
        }
      ]
    });
    
    // Or send an email
    sendEmail({
      to: 'ops@yourcompany.com',
      subject: `WaSphere Alert: Session "${sessionName}" disconnected`,
      body: `Reason: ${reason}. Please check: https://wa.yourdomain.com`,
    });
  }
});

See Webhooks for the full event list and payload schemas.

Resource Monitoring

View container resource usage

# Live stats for all WaSphere containers
docker stats $(docker compose ps -q)

Example output:

CONTAINER             CPU %   MEM USAGE / LIMIT   NET I/O         BLOCK I/O
wasphere-wa-server    0.8%    312MiB / 2GiB       1.2GB / 450MB   0B / 0B
wasphere-dashboard-api 0.3%   178MiB / 2GiB       890MB / 1.1GB   0B / 0B
wasphere-dashboard-ui 0.2%    96MiB / 2GiB        120MB / 40MB    0B / 0B
wasphere-postgres     0.1%    89MiB / 2GiB        230MB / 180MB   45GB / 12GB

Resource limits in docker-compose.yml

Prevent any single service from consuming all server resources:

services:
  wa-server:
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          memory: 256M

  dashboard-api:
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 256M

Delivery Failures

WaSphere sends messages and webhooks directly — there is no background queue to inspect. To track delivery health:

• Webhook failures — every attempt is recorded in the dashboard's webhook delivery log, with the response status and retry count. Repeated failures to one endpoint mean that endpoint is down or rejecting requests.
• Message failures — bulk sends return a per-recipient outcome (sent / failed) in the API response, so your caller sees failures immediately. A session that flips to disconnected is the usual cause — watch the health endpoint and the session.disconnected webhook (above).