Skip to main content
Monocle can monitor your services availability by periodically checking your health endpoints. Get notified when something goes wrong and track your uptime over time.

​
How It Works

Monocle pings your configured URL once per minute. By default, it simply checks if your endpoint responds with a 2xx status code. But with Health Mode enabled, Monocle goes further by parsing the response body to understand the detailed health status of your services.

​
Health Mode

Health Mode allows Monocle to understand what’s happening inside your application. Instead of just checking “is the server responding?”, it parses a structured health response to detect degraded services—even when the endpoint technically returns a 200 OK. For example, your API might respond successfully while your database connection is failing. With Health Mode, Monocle detects this and creates an incident.

​
Response Format

Your health endpoint must return a JSON response matching this structure: 
{
  "isHealthy": true,
  "status": "ok",
  "finishedAt": "2026-01-01T20:50:11.945Z",
  "checks": [
    {
      "name": "Database health check (postgres)",
      "isCached": false,
      "message": "Successfully connected to the database server",
      "status": "ok",
      "finishedAt": "2026-01-01T20:50:11.945Z",
      "meta": {
        "connection": {
          "name": "postgres",
          "dialect": "postgres"
        }
      }
    },
    {
      "name": "Redis health check (main)",
      "isCached": false,
      "message": "Successfully connected to the redis server",
      "status": "ok",
      "finishedAt": "2026-01-01T20:50:11.944Z",
      "meta": {
        "connection": {
          "name": "main",
          "status": "ready"
        }
      }
    }
  ]
}
FieldTypeDescription
isHealthybooleanOverall health status
statusstring"ok", "warning", or "error"
finishedAtstringISO 8601 timestamp
checksarrayIndividual health check results
checks[].namestringName of the health check
checks[].statusstring"ok", "warning", "failed", "crashed", or "skipped"
checks[].messagestringHuman-readable status message
checks[].metaobjectOptional metadata about the check

​
AdonisJS Integration

If you’re using AdonisJS, this format is natively supported by the health checks module. Follow the AdonisJS Health Checks guide to set up your health endpoint. Once configured, your /health endpoint will automatically return the expected format and work seamlessly with Monocle’s Health Mode.

​
Configuring a Monitor

Navigate to the Uptime section in your dashboard and click Configure to set up your monitor.

​
Basic Settings

SettingDescription
URLThe health endpoint URL to monitor
Health ModeEnable to parse the structured health response

​
Advanced Settings

SettingDefaultDescription
Timeout10sHow long to wait before considering a check failed (1-30 seconds)
Custom Headers-Add custom HTTP headers (useful for authentication)
Failure Tolerance3Number of consecutive failures before creating an incident
Recovery Tolerance1Number of consecutive successes before resolving an incident

​
Custom Headers

If your health endpoint requires authentication, you can add custom headers: 
Authorization: Bearer your-api-token
X-Custom-Header: some-value

​
Check Details

Click on any check in the uptime timeline to see detailed results. When Health Mode is enabled, you’ll see the status of each individual health check (database, Redis, disk space, etc.). This makes it easy to understand exactly what failed and why, without digging through logs.

​
Incident Thresholds

To avoid false alarms from temporary network issues, Monocle uses tolerance thresholds:
  • Failure Tolerance: An incident is only created after this many consecutive failures. Set it higher if you experience occasional network hiccups.
  • Recovery Tolerance: An incident is resolved after this many consecutive successes. Keep it at 1 for fast recovery notifications, or increase it to ensure the service is truly stable.