Uptime Monitoring

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"
        }
      }
    }
  ]
}

Field	Type	Description
`isHealthy`	boolean	Overall health status
`status`	string	`"ok"`, `"warning"`, or `"error"`
`finishedAt`	string	ISO 8601 timestamp
`checks`	array	Individual health check results
`checks[].name`	string	Name of the health check
`checks[].status`	string	`"ok"`, `"warning"`, `"failed"`, `"crashed"`, or `"skipped"`
`checks[].message`	string	Human-readable status message
`checks[].meta`	object	Optional 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

Setting	Description
URL	The health endpoint URL to monitor
Health Mode	Enable to parse the structured health response

Advanced Settings

Setting	Default	Description
Timeout	10s	How long to wait before considering a check failed (1-30 seconds)
Custom Headers	-	Add custom HTTP headers (useful for authentication)
Failure Tolerance	3	Number of consecutive failures before creating an incident
Recovery Tolerance	1	Number 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.

Getting Started

Monocle Studio

Frameworks

Features

Integrations

Other

How It Works

Health Mode

Response Format

AdonisJS Integration

Configuring a Monitor

Basic Settings

Advanced Settings

Custom Headers

Check Details

Incident Thresholds

​How It Works

​Health Mode

​Response Format

​AdonisJS Integration

​Configuring a Monitor

​Basic Settings

​Advanced Settings

​Custom Headers

​Check Details

​Incident Thresholds

How It Works

Health Mode

Response Format

AdonisJS Integration

Configuring a Monitor

Basic Settings

Advanced Settings

Custom Headers

Check Details

Incident Thresholds