Network Monitors

Overview

Network Monitors let you define recurring checks against IP addresses, hostnames, ports, HTTP endpoints, and DNS records. Breeze dispatches each check through a connected agent in the same organization via WebSocket, records the result, and updates the monitor’s status. Monitors can optionally be linked to a discovered asset so that availability data appears alongside the asset’s SNMP and discovery information.

All monitor operations require authentication and one of the organization, partner, or system scopes. Organization-scoped users are automatically restricted to monitors within their own organization.

Monitor Types

Breeze supports four monitor types, stored in the monitor_type PostgreSQL enum:

| Type | DB Value | What It Checks | |---|---|---| | ICMP Ping | icmp_ping | Sends ICMP echo requests to a target host. Measures round-trip time. | | TCP Port | tcp_port | Opens a TCP connection to a specific port. Optionally checks for a banner string. | | HTTP/Endpoint | http_check | Makes an HTTP request to a URL. Validates status code, response body, SSL, and redirects. | | DNS | dns_check | Resolves a hostname via DNS. Optionally checks record type, expected value, and nameserver. |

ICMP Ping Configuration

| Field | Type | Constraints | Default | Description | |---|---|---|---|---| | count | integer | 1 — 20 | none | Number of echo requests to send. | | packetSize | integer | 16 — 65,535 | none | ICMP packet payload size in bytes. |

TCP Port Configuration

| Field | Type | Constraints | Default | Description | |---|---|---|---|---| | port | integer | 1 — 65,535 | required | TCP port number to connect to. | | expectBanner | string | optional | none | String the server banner must contain for a successful check. |

HTTP/Endpoint Configuration

| Field | Type | Constraints | Default | Description | |---|---|---|---|---| | url | string | valid URL | none | Full URL to request. If omitted, the monitor’s target field is used. | | method | enum | GET, HEAD, POST, PUT, OPTIONS | none | HTTP method. | | expectedStatus | integer | 100 — 599 | none | Required HTTP status code for a passing check. | | expectedBody | string | optional | none | Substring that must appear in the response body. | | headers | object | key-value pairs | none | Custom HTTP headers to include in the request. | | followRedirects | boolean | optional | none | Whether to follow HTTP redirects. | | verifySsl | boolean | optional | none | Whether to verify the TLS certificate. |

DNS Check Configuration

| Field | Type | Constraints | Default | Description | |---|---|---|---|---| | hostname | string | min 1 char | none | Hostname to resolve. If omitted, the monitor’s target field is used. | | recordType | enum | A, AAAA, MX, CNAME, TXT, NS | none | DNS record type to query. | | expectedValue | string | optional | none | Expected value in the DNS response. | | nameserver | string | optional | none | Custom DNS nameserver to query. |

Creating a Monitor

1. Choose a target. Identify the IP address, hostname, or URL you want to monitor. Optionally associate the monitor with a discovered asset by providing its assetId.

2. Select a monitor type. Pick one of icmp_ping, tcp_port, http_check, or dns_check.

3. Send a POST request.

   curl -X POST /api/v1/monitors \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Web Server HTTPS",
       "monitorType": "http_check",
       "target": "https://app.example.com",
       "config": {
         "method": "GET",
         "expectedStatus": 200,
         "verifySsl": true
       },
       "pollingInterval": 120,
       "timeout": 10
     }'

4. Verify the response. A 201 status with the full monitor object confirms creation. The monitor begins in unknown status and isActive: true.

Tip

When you provide an assetId, the API validates that the asset exists and belongs to the same organization. If you also supply an explicit orgId, it must match the asset’s organization.

Polling Intervals and Timeouts

| Parameter | Column | Min | Max | Default | Unit | |---|---|---|---|---|---| | pollingInterval | polling_interval | 10 | 86,400 | 60 | seconds | | timeout | timeout | 1 | 300 | 5 | seconds |

The polling interval controls how frequently the BullMQ scheduler enqueues a check job for the monitor. The timeout is passed to the agent as the maximum time allowed for the check to complete before it is considered failed.

Note

The scheduler runs every 30 seconds. A monitor becomes due for a check when last_checked + polling_interval is at or before the current time, or when last_checked is NULL (never checked). Setting a polling interval below 30 seconds means the monitor will be checked on every scheduler cycle.

Monitor Status Lifecycle

Each monitor tracks a last_status field with one of four values:

| Status | Meaning | |---|---| | unknown | Initial state. No check has completed yet. | | online | The most recent check succeeded. | | degraded | The check succeeded but with concerning metrics (e.g., high response time). | | offline | The most recent check failed. |

Consecutive Failures

The consecutive_failures counter increments by 1 each time a check result has status offline. It resets to 0 on any non-offline result (online or degraded). This counter is used by alert rules with the consecutive_failures_gt condition.

State Update Transaction

When a check result is processed, the worker updates both the network_monitor_results row and the parent network_monitors row inside a single database transaction. The fields updated on the monitor are:

• last_checked — timestamp of the check
• last_status — the result status
• last_response_ms — response time in milliseconds
• last_error — error message (or NULL on success)
• consecutive_failures — incremented or reset
• updated_at — current timestamp

Results and Response Times

Every completed check writes a row to the network_monitor_results table:

| Column | Type | Description | |---|---|---| | id | UUID | Primary key. | | monitor_id | UUID | Foreign key to network_monitors. Cascades on delete. | | status | enum | online, offline, degraded, or unknown. | | response_ms | real | Response time in milliseconds. | | status_code | integer | HTTP status code (HTTP checks only). | | error | text | Error message if the check failed. | | details | JSONB | Additional check-specific data returned by the agent. | | timestamp | timestamp | When the check was performed. |

Querying Results

Fetch historical results with optional time-range filtering:

curl "/api/v1/monitors/<monitorId>/results?start=2026-02-01T00:00:00Z&end=2026-02-18T00:00:00Z&limit=500" \
  -H "Authorization: Bearer <token>"

| Query Parameter | Type | Constraints | Default | Description | |---|---|---|---|---| | start | string | ISO 8601 datetime | none | Include results on or after this timestamp. | | end | string | ISO 8601 datetime | none | Include results on or before this timestamp. | | limit | integer | 1 — 1,000 | 100 | Maximum number of results to return. |

Results are returned in descending order by timestamp (newest first).

Dashboard Stats

The GET /api/v1/monitors/dashboard endpoint returns aggregate counts for the authenticated organization:

{
  "data": {
    "total": 12,
    "status": {
      "online": 8,
      "offline": 2,
      "degraded": 1,
      "unknown": 1
    },
    "types": {
      "icmp_ping": 4,
      "tcp_port": 3,
      "http_check": 4,
      "dns_check": 1
    }
  }
}

The response includes:

• total — total number of monitors in the organization.
• status — count of monitors grouped by their current last_status.
• types — count of monitors grouped by monitor_type.

Alert Rules on Monitors

Each monitor can have one or more alert rules. Alert rules are evaluated against check results to trigger alerts at the configured severity level.

Alert Rule Conditions

| Condition | Description | Threshold | |---|---|---| | offline | Fires when the monitor status is offline. | Not used. | | degraded | Fires when the monitor status is degraded. | Not used. | | response_time_gt | Fires when response time exceeds the threshold. | Milliseconds (string). | | consecutive_failures_gt | Fires when consecutive failures exceed the threshold. | Failure count (string). |

Alert Rule Severities

Rules use the shared alert_severity enum: critical, high, medium, low, info.

Creating an Alert Rule

curl -X POST /api/v1/monitors/alerts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "monitorId": "<monitorId>",
    "condition": "consecutive_failures_gt",
    "threshold": "3",
    "severity": "critical",
    "message": "Web server has failed 3+ consecutive checks"
  }'

Alert Rule Schema

| Field | Type | Required | Default | Description | |---|---|---|---|---| | monitorId | UUID | Yes | — | The monitor this rule applies to. | | condition | enum | Yes | — | One of offline, degraded, response_time_gt, consecutive_failures_gt. | | threshold | string | No | null | Threshold value for response_time_gt and consecutive_failures_gt. | | severity | enum | Yes | — | Alert severity: critical, high, medium, low, info. | | message | string | No | null | Custom message included in the alert. | | isActive | boolean | No | true | Whether this rule is currently active. |

Caution

Alert rules cascade-delete when their parent monitor is deleted. Deleting a monitor removes all associated rules and historical results.

Testing Monitors

The test endpoint sends a one-off check command to a connected agent without going through the BullMQ queue. It finds an online agent in the monitor’s organization and dispatches the command directly via WebSocket.

curl -X POST /api/v1/monitors/<monitorId>/test \
  -H "Authorization: Bearer <token>"

Response (success):

{
  "data": {
    "monitorId": "<monitorId>",
    "status": "queued",
    "testedAt": "2026-02-18T12:00:00.000Z"
  }
}

Response (no agent available):

{
  "data": {
    "monitorId": "<monitorId>",
    "status": "failed",
    "error": "No online agent available",
    "testedAt": "2026-02-18T12:00:00.000Z"
  }
}

Note

The test endpoint requires at least one online, WebSocket-connected agent in the monitor’s organization. If no agent is connected, the test returns immediately with a failed status rather than an HTTP error.

On-Demand Checks via BullMQ

The check endpoint enqueues a monitor check job through BullMQ rather than dispatching directly. This is the same mechanism the scheduler uses for recurring checks, but triggered manually.

curl -X POST /api/v1/monitors/<monitorId>/check \
  -H "Authorization: Bearer <token>"

Response:

{
  "data": {
    "monitorId": "<monitorId>",
    "status": "queued",
    "message": "Check request queued"
  }
}

How the Job Queue Works

The monitor system uses a BullMQ queue named monitors with three job types:

| Job Type | Name | Description | |---|---|---| | check-monitor | Check Monitor | Looks up the monitor, finds an online agent in the org, and dispatches the check command via WebSocket. | | process-check-result | Process Check Result | Writes the result to network_monitor_results and updates the monitor’s state in a transaction. | | monitor-scheduler | Monitor Scheduler | Repeatable job (every 30 seconds) that finds all active monitors due for a check and enqueues check-monitor jobs. |

The worker processes jobs with a concurrency of 10. Completed jobs are retained (100 for success, 200 for failures) for debugging.

Caution

The check endpoint requires Redis. If Redis is unavailable, the endpoint returns 503 Service Unavailable with the message “Check service unavailable. Redis is required for job queuing.”

Agent Command Mapping

Each monitor type maps to a specific agent command type:

| Monitor Type | Agent Command | |---|---| | icmp_ping | network_ping | | tcp_port | network_tcp_check | | http_check | network_http_check | | dns_check | network_dns_check |

The command payload includes the monitor’s target, timeout, and all fields from the monitor’s config object. Command IDs follow the pattern mon-<monitorId>-<timestamp>.

API Reference

All endpoints are mounted at /api/v1/monitors and require authentication.

Monitors

| Method | Path | Description | |---|---|---| | GET | /api/v1/monitors | List monitors with optional filters. | | POST | /api/v1/monitors | Create a new monitor. | | GET | /api/v1/monitors/dashboard | Aggregate status and type counts. | | GET | /api/v1/monitors/:id | Get a single monitor with recent results and alert rules. | | PATCH | /api/v1/monitors/:id | Update monitor fields. | | DELETE | /api/v1/monitors/:id | Delete a monitor and all associated results/rules. | | POST | /api/v1/monitors/:id/check | Enqueue an on-demand check via BullMQ. | | POST | /api/v1/monitors/:id/test | Send a direct test check to an online agent. | | GET | /api/v1/monitors/:id/results | Query historical check results. |

Alert Rules

| Method | Path | Description | |---|---|---| | POST | /api/v1/monitors/alerts | Create an alert rule for a monitor. | | GET | /api/v1/monitors/:monitorId/alerts | List alert rules for a monitor. | | PATCH | /api/v1/monitors/alerts/:id | Update an alert rule. | | DELETE | /api/v1/monitors/alerts/:id | Delete an alert rule. |

List Monitors Query Parameters

| Parameter | Type | Description | |---|---|---| | orgId | UUID | Filter by organization. Required for partner and system scopes. | | assetId | UUID | Filter by discovered asset. Also infers orgId from the asset. | | monitorType | enum | Filter by type: icmp_ping, tcp_port, http_check, dns_check. | | status | enum | Filter by current status: online, offline, degraded, unknown. | | search | string | Search by monitor name or target (substring match). |

Monitoring Assets Integration

Network monitors also surface through the /api/v1/monitoring/assets endpoint, which returns discovered assets enriched with their monitoring configuration. Each asset includes a network object showing:

{
  "network": {
    "configured": true,
    "totalCount": 3,
    "activeCount": 2
  }
}

The DELETE /api/v1/monitoring/assets/:id endpoint disables all active network monitors (and SNMP devices) for a given asset by setting isActive to false.

Troubleshooting

Monitor stuck in “unknown” status

The monitor has never been checked. Verify that:

1. The monitor has isActive: true.
2. At least one agent in the same organization is online and connected via WebSocket.
3. Redis is running and the monitor worker has been initialized (look for [MonitorWorker] Monitor worker initialized in API logs).
4. The scheduler repeatable job is registered (look for [MonitorWorker] Scheduled repeatable monitor scheduler (every 30s) in logs).

Check dispatched but no result recorded

The agent received the command but did not return a result. Check:

1. Agent logs for errors processing the network_ping, network_tcp_check, network_http_check, or network_dns_check command.
2. WebSocket connectivity between the agent and the API.
3. That the process-check-result job type is being processed (check BullMQ failed jobs for errors).

”Check service unavailable” (503)

The /check endpoint requires Redis for BullMQ job queuing. Ensure Redis is running and the REDIS_URL environment variable is correctly configured.

”No online agent available” on test

The /test endpoint looks for a device with status: 'online' in the monitor’s organization and verifies it has an active WebSocket connection. Ensure at least one agent is enrolled, heartbeating, and connected.

Monitors not running on schedule

The scheduler is a BullMQ repeatable job that runs every 30 seconds. If monitors are not being checked:

1. Verify the worker is running — check for [MonitorWorker] log lines.
2. Inspect the monitors queue in Redis for stuck or failed jobs.
3. Confirm the monitor’s polling_interval has elapsed since last_checked.

Alert rules not firing

Alert rules are stored in the network_monitor_alert_rules table. Verify:

1. The rule has isActive: true.
2. The condition and threshold match the current monitor state (e.g., consecutive_failures_gt with threshold "3" requires consecutive_failures > 3).
3. The monitor’s check results are being recorded — query the /results endpoint to confirm.