Network Checks

Overview

Network checks probe IP addresses, hostnames, ports, HTTP endpoints and DNS records from connected agents. Author their conditions and alert behavior as monitors; inspect probe results on the Network page. Access is restricted to authorized organizations.

In the console

Network checks are authored as monitors of kind Network check under Alerts → Monitors. The Network page (Fleet Management → Network, /monitoring; called Network Monitor before this release) keeps Assets, SNMP Templates and Results.

Results lists checks with their last status and response time, and links managed checks to the monitor that owns them. Unconverted checks show a conversion note. New check opens the monitor editor with the kind pre-selected; opening it from an asset or network device page also pre-binds the asset. The old /monitoring#checks link lands on Results. Results and detail views retain history and operational checks; edit conditions in Monitors.

Network check fields

Field	API condition field	Range or behavior
Check type	checkType	icmp_ping, tcp_port, http_check, dns_check
Target	target	IP address, hostname or URL; 1–500 characters
Asset binding	assetId	Optional discovered asset in the monitor’s organization. Pins execution to its current site and guides alert-device selection. Partner-wide definitions cannot bind an asset.
Treat degraded as failure	degradedIsFailure	Default false; count degraded results as failures
Fail when slower than	maxResponseMs	Optional 1–600,000 ms; a response above this limit counts as a failure
Poll interval	pollingIntervalSeconds	10 seconds–24 hours; default 60 seconds
Timeout	timeoutSeconds	1–300 seconds; default 5 seconds
Consecutive failures	consecutiveFailures	1–100; default 2

Offline results always count as failures. With the optional degraded or slow predicates enabled, each consecutive result must match at least one failure predicate. No results means unknown, not a breach. Asset binding does not replace the target: enter the endpoint to probe separately.

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	Preserved configuration; currently ignored by the agent.

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
target	string	URL	required	URL to request; legacy config.url maps here during conversion.
method	enum	GET, HEAD, POST, PUT, OPTIONS	none	HTTP method.
expectStatus	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	string key-value pairs	none	Preserved configuration; currently ignored by the agent.
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
target	string	min 1 char	required	Hostname to resolve; legacy config.hostname maps here during conversion.
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.

The monitor-definition API calls the HTTP field expectStatus; the compiler sends it to the agent as expectedStatus. This mapping was fixed in #6352 and is retained. For new checks expecting a 3xx status, redirects default to false unless explicitly overridden; otherwise they default to true. Conversion explicitly preserves the legacy redirect setting (true when absent).

Options belong to the selected check type. The monitor editor exposes common options; the API also preserves packetSize and headers, though agents currently ignore both.

Creating a check

1. Open Alerts → Monitors → New monitor and choose Network check.
2. Set the type, target, optional asset and type-specific options.
3. Configure severity, cooldown, automatic resolution, responses and Notify.
4. Save and attach the monitor to a configuration policy assigned to the intended organization or devices to enable alert evaluation. Saving an enabled network-check definition provisions an active probe; policy attachment determines which devices can receive its alerts.
5. Open Network → Results to inspect the check and run an on-demand probe.

Polling Intervals and Timeouts

Parameter	Column	Min	Max	Default	Unit
pollingIntervalSeconds	polling_interval	10	86,400	60	seconds
timeoutSeconds	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). Retained legacy rules use this counter. Managed monitors evaluate consecutive result history, including degraded or slow results when configured.

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.

Alerting

One managed network check raises one monitor alert per running organization. The alert attaches to the asset’s linked device, otherwise the most recently seen non-ephemeral device in its site, then the organization. The selected device must be reached by an enabled monitor attachment; if necessary, Breeze selects an eligible device in the organization instead.

Evaluation runs once per managed check per organization even when that alert device is offline, using the legacy worker’s selection preference with the monitor’s attachment scope enforced. The executing agent still needs to be online. Maintenance windows are enforced by the shared monitor evaluator.

Severity, cooldown, automatic resolution and Notify (Inherit, Channels, Inbox only) come from the monitor. Delivery follows routing; there is no fallback to all channels. Escalation resolves from the monitor, then the matching routing row, then no policy (monitor → row → null). Inbox only suppresses escalation. See Delivery.

• Five-minute cooldown by default. Converted checks use a five-minute cooldown per monitor and alert device; change it in the monitor’s noise settings.
• Deduplication while an alert is open. Repeated failures update the existing episode for that monitor and device instead of stacking alerts. Recovery resolves it when automatic resolution is enabled.

Managed alert.triggered events carry the definition’s monitorId and kind: network_check, which Alert workflows can filter on. Unmanaged checks keep their legacy alert identity until converted.

Converting existing checks

Open the conversion banner on Network → Results, preview the proposed monitors and confirm conversion. Existing unmanaged checks keep polling and alerting until you convert or explicitly retire them. Startup conversion and retirement never process network sources.

A check with exactly one active, unretired rule can map as follows:

Legacy rule	Monitor condition
offline	consecutiveFailures: 1
consecutive_failures_gt with threshold N	consecutiveFailures: floor(N) + 1, preserving the strict greater-than comparison

The threshold must be finite and nonnegative, and the resulting failure count must fit 1–100. Conversion preserves severity, the rule message as the description, effective target and timeout, supported per-type configuration, asset binding and enabled state. Notify is Inherit, cooldown is five minutes and automatic resolution is enabled. The preview reports config keys without a monitor equivalent.

Conversion adopts the existing probe row, preserving its result history. Monitors are attached to a dedicated Network checks — <org name> policy, assigned at organization level with cumulative inheritance and no filters. A previously generated policy is reused only while it still meets those requirements.

The preview refuses checks it cannot represent exactly:

Reason	Meaning
no_active_rules	Non-alerting probe; conversion must not introduce alerts
multiple_network_rules	Multiple active rules, including mixed predicates or severities
network_predicate_unsupported	A degraded-only or response-time-only legacy predicate
network_threshold_out_of_range	Failure threshold cannot map to 1–100
site_binding_unrepresentable	Site-only binding without an asset
asset_missing, condition_invalid	Missing asset or options outside the monitor schema
config_override_unrepresentable	Legacy execution override cannot be preserved
already_managed, no_org	Source already managed or lacks organization ownership

API refusal reasons have an unconvertible: prefix. Degraded and slow predicates can be authored on new monitors, but their legacy-only alert semantics are not silently changed by conversion.

If the required device-independent runtime capability from #6353 is missing, the entire network preview is blocked (prerequisite_missing), with no items or per-check refusals. Nothing is automatically retired. Interactive partner Convert everything reports network sources as blocked while other eligible source types can still convert; a capability change requires a fresh preview.

Open legacy alerts retain active, acknowledged or suppressed status and provenance when moved to the monitor. Conversion and retirement never resolve them. Retire stops an unwanted source and records its name and reason in the persistent conversion ledger, even if no monitor was created. Conversion history → Undo can revert network conversion or retirement while the network runtime remains available. Revert restores the source and alert references; asset-bound checks use the asset’s current site. Deleting an adopted monitor preserves the probe and history as retired rather than deleting them.

Testing Monitors

The test endpoint sends a one-off check command to a connected agent without going through the BullMQ queue. It finds an eligible online agent in the check’s organization (in the bound asset’s site when bound) 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 an eligible online, WebSocket-connected agent in the check’s organization, restricted to the asset’s site when bound. 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	410 Gone; author a network_check monitor definition.
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	410 Gone.
DELETE	/api/v1/monitors/:id	410 Gone for unmanaged rows; managed rows return an ownership conflict directing you to Monitors. Use ledger retirement for unmanaged cleanup.
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	410 Gone.
GET	/api/v1/monitors/:monitorId/alerts	List alert rules for a monitor.
PATCH	/api/v1/monitors/alerts/:id	410 Gone.
DELETE	/api/v1/monitors/alerts/:id	410 Gone.

Retired authoring responses use this body (normal authentication and authorization still apply):

{
  "error": "network_check_authoring_retired",
  "message": "Network checks are authored as monitors. Create or edit a monitor of kind network_check under Alerts → Monitors.",
  "hint": { "route": "POST /monitor-definitions", "kind": "network_check" }
}

Reads and operational /check and /test endpoints remain available. List results include managedByMonitorId (the owning definition, or null) and retiredAt. Retired checks are excluded by default.

Conversion endpoints

Paths below are relative to /api/v1/monitor-definitions/conversion. Conversion writes require alert-write permission and MFA; network conversion requires organization-wide access.

Method	Path	Request
GET	/network-checks?orgId=<uuid>	Preview, including previewHash, proposed monitors and refusals
POST	/network-checks/convert	{ orgId, previewHash, sourceIds? }; optional selection of up to 500 source IDs
POST	/retire	{ sourceTable: "network_monitors", sourceId, reason: "operator" }
GET	/ledger?orgId=<uuid>	Persistent history; returns { items, nextCursor }
POST	/:conversionId/revert	Undo network conversion or retirement

Confirm with the current preview hash. Authoring changes invalidate it; new telemetry does not. Pending counts expose data.networkChecks separately from legacy rows.

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).
includeRetired	boolean	Set to true to include retained retired rows.

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 device action is Disable SNMP monitoring and uses the existing SNMP PATCH endpoint. It does not disable network checks.

DELETE /api/v1/monitoring/assets/:id returns 409 network_checks_active before changing anything when checks are active. Its checks list identifies managed checks by monitorId (disable in Monitors); unmanaged checks must be converted or retired.

DELETE /api/v1/discovery/assets/:id returns 409 asset_has_retained_network_checks while any retained check is bound to the asset, including retired checks. Retained history is not silently deleted.

Troubleshooting

Monitor stuck in “unknown” status

The monitor has never been checked. Verify that:

1. The monitor has isActive: true.
2. An eligible agent in the same organization (and asset site when bound) 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 requires an eligible online device with an active WebSocket connection. For an asset-bound check, the agent must be in the asset’s current site; there is no organization-wide fallback. Ensure a suitable 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.

The monitor is not firing

1. Confirm the definition is attached to an assigned configuration policy and enabled for an eligible alert device. Asset binding alone does not enable alert evaluation.
2. Check /results for enough consecutive failures. Degraded and slow results count only when the corresponding options are enabled.
3. Review maintenance windows, cooldown and the existing open episode.
4. If the alert exists but no notification arrives, inspect Notify and the matching Delivery routing row. Inbox only intentionally sends no notification.
5. For an unconverted check, inspect its retained rules. A probe without an active rule remains non-alerting; use the conversion preview to see any refusal reason.