IcmpMonitor Construct

Learn more about ICMP Monitors in the ICMP monitor overview.

ICMP monitors check if a host is reachable by sending ICMP Echo Requests (pings). Use them to monitor network connectivity and latency.

Prerequisites

Before creating ICMP Monitors, ensure you have:

An initialized Checkly CLI project
A hostname or IP address you want to ping
Basic understanding of network connectivity (ICMP / ping)

For additional setup information, see CLI overview.

import { Frequency, IcmpMonitor } from "checkly/constructs"

new IcmpMonitor('icmp-welcome', {
  name: 'Welcome Site Reachability',
  description: "Pings `welcome.checklyhq.com` to verify **host reachability**.",
  frequency: Frequency.EVERY_1M,
  request: {
    hostname: 'welcome.checklyhq.com',
  },
  degradedPacketLossThreshold: 20, // percentage
  maxPacketLossThreshold: 30, // percentage
})

import { Frequency, IcmpAssertionBuilder, IcmpMonitor } from "checkly/constructs"

new IcmpMonitor('cloudflare-dns-icmp', {
  name: 'Cloudflare DNS ICMP Monitor',
  description: "Cloudflare DNS reachability and latency check.",
  activated: true,
  frequency: Frequency.EVERY_1M,
  maxPacketLossThreshold: 20, // percentage
  degradedPacketLossThreshold: 10,
  request: {
    hostname: '1.1.1.1',
    pingCount: 20,
    assertions: [
      IcmpAssertionBuilder.latency('avg').lessThan(100),
      IcmpAssertionBuilder.latency('max').lessThan(200),
    ]
  }
})

Configuration

ICMP monitors have their own ICMP-specific settings, plus the standard monitor options shared across all check types.

ICMP Monitor Settings
General Monitor Settings

Parameter	Type	Required	Default	Description
`request`	`object`	✅	-	ICMP request configuration object
`intent`	`CheckIntent`	❌	-	Structured guidance for root cause analysis and check repair. See General Monitor Options.
`degradedPacketLossThreshold`	`number`	❌	`10`	Packet loss percentage at which the monitor is marked as degraded
`maxPacketLossThreshold`	`number`	❌	`20`	Packet loss percentage at which the monitor is marked as failed

Property	Type	Required	Default	Description
`name`	`string`	✅	-	Friendly name for your monitor
`description`	`string`	❌	`null`	A description of the monitor. Supports markdown. Max 500 characters
`activated`	`boolean`	❌	`true`	Whether the monitor is enabled
`alertChannels`	`Array<AlertChannel \| AlertChannelRef>`	❌	`[]`	Array of AlertChannel objects for notifications
`alertEscalationPolicy`	`AlertEscalationPolicy`	❌	-	Advanced alert escalation settings
`frequency`	`Frequency`	❌	`EVERY_10M`	How often to run your monitor
`group`	`CheckGroupV1` `CheckGroupV2`	❌	-	The CheckGroup this monitor belongs to
`locations`	`string[]`	❌	`[]`	Array of public location codes
`privateLocations`	`string[]`	❌	`[]`	Array of Private Location slugs
`muted`	`boolean`	❌	`false`	Whether alert notifications are muted
`tags`	`string[]`	❌	`[]`	Array of tags to organize monitors
`testOnly`	`boolean`	❌	`false`	Only run with test, not during deploy
`retryStrategy`	`RetryStrategy`	❌	-	Strategy for configuring retries
`runParallel`	`boolean`	❌	`false`	Run monitors in parallel or round-robin
`triggerIncident`	`IncidentTrigger`	❌	-	Create and resolve an incident based on the check’s alert configuration

`IcmpMonitor` Options

object

required

ICMP request configuration, including ping settings and response validation.Usage:

new IcmpMonitor('icmp-monitor', {
  name: 'ICMP Latency Monitor',
  request: {
    hostname: 'api.checklyhq.com',
    pingCount: 15,
    assertions: [
      IcmpAssertionBuilder.latency('avg').lessThan(100),
    ]
  }
})

Parameters:

Parameter	Type	Required	Default	Description
`hostname`	`string`	✅	-	The target host (domain name or IP address)
`pingCount`	`number`	❌	`10`	Number of ICMP Echo Request packets to send per check run (1-50, default: 10)
`assertions`	`IcmpAssertion[]`	❌	`[]`	Response assertions using the `IcmpAssertionBuilder`
`ipFamily`	`string`	❌	`IPv4`	IP family selection (IPv4, IPv6)

number

default:"10"

Packet loss percentage at which the monitor is marked as degraded (warning state).Usage:

new IcmpMonitor("icmp-performance-tiers", {
  name: "ICMP Performance Tiers",
  degradedPacketLossThreshold: 15, // Warn at 15%
  request: {
    hostname: '1.1.1.1',
    pingCount: 20,
  }
})

number

default:"20"

Packet loss percentage at which the monitor is marked as failedUsage:

new IcmpMonitor("icmp-performance-tiers", {
  name: "ICMP Performance Tiers",
  maxPacketLossThreshold: 25, // Fail at 25%
  request: {
    hostname: '1.1.1.1',
    pingCount: 20,
  }
})

`IcmpMonitor` Assertions

Assertions for ICMP monitors can be defined using the IcmpAssertionBuilder. The following sources are available:

latency(property): Validate round-trip time (RTT) for ICMP pings. The property parameter is required and must be one of: avg, min, max, or stdDev
jsonResponse(property?): Assert against the JSON response structure. This allows you to target specific fields using JSON path assertions

Here are some examples:

Assert the average latency is below a threshold

IcmpAssertionBuilder.latency('avg').lessThan(100)
// Equivalent to:
{ source: 'LATENCY', property: 'avg', comparison: 'LESS_THAN', target: '100' }

Assert against specific JSON fields in the response

IcmpAssertionBuilder.jsonResponse('$.packetsReceived').equals(10)
// Equivalent to:
{ source: 'JSON_RESPONSE', property: '$.packetsReceived', comparison: 'EQUALS', target: '10' }

Learn more in our docs on Assertions.

General Monitor Options

string

required

Friendly name for your ICMP Monitor that will be displayed in the Checkly dashboard and used in notifications.Usage:

new IcmpMonitor("my-monitor", {
  name: "ICMP Ping Monitor",
  /* More options ... */
})

Frequency

How often the ICMP Monitor should run. Use the Frequency enum to set the check interval.Usage:

new IcmpMonitor("my-monitor", {
  name: "ICMP Ping Monitor",
  frequency: Frequency.EVERY_1M,
  /* More options ... */
})

Available frequencies: EVERY_10S, EVERY_20S, EVERY_30S, EVERY_1M, EVERY_2M, EVERY_5M, EVERY_10M, EVERY_15M, EVERY_30M, EVERY_1H, EVERY_2H, EVERY_3H, EVERY_6H, EVERY_12H, EVERY_24H

string[]

default:"[]"

Array of public location codes where the ICMP Monitor should run from. Multiple locations provide geographic coverage and help detect regional network issues.Usage:

new IcmpMonitor("global-icmp-monitor", {
  name: "ICMP Ping Monitor",
  locations: ["us-east-1", "eu-central-1", "ap-southeast-1"]
})

boolean

default:"true"

Whether the ICMP Monitor is enabled and will run according to its schedule.Usage:

new IcmpMonitor("my-monitor", {
  name: "ICMP Ping Monitor",
  activated: false // Disabled monitor
})

CheckIntent

Describe what your check is intended to verify and the behavior that should be preserved. Checkly uses intent for root cause analysis across all check types. It is separate from description and does not replace executable assertions.

Intent is used for automatic repair only for Browser and Multistep Checks.

The object accepts the following fields:

Field	Type	Required	Description
`goal`	`string`	Yes	The outcome your check should verify. Must contain 1–2,000 characters after trimming.
`constraints`	`CheckIntentConstraint[]`	No	Outcomes and guardrails that refine the goal. Omitted constraints become an empty array.

Each constraint has a required type and statement:

REQUIRED_OUTCOME: an outcome the check must verify.
MUST_PRESERVE: behavior or an assertion that should be preserved when repairing the check.

Each statement must contain 1–1,000 characters after trimming. You can specify at most 20 constraints of each type. The CLI trims leading and trailing whitespace from the goal and statements and rejects unknown fields.For example, configure intent on a Browser Check:

import { BrowserCheck } from "checkly/constructs"

new BrowserCheck("dashboard-intent", {
  name: "Authenticated dashboard",
  code: {
    entrypoint: "./dashboard.spec.ts",
  },
  intent: {
    goal: "Verify that authenticated users can open the dashboard.",
    constraints: [
      {
        type: "REQUIRED_OUTCOME",
        statement: "Authentication succeeds for a valid user.",
      },
      {
        type: "MUST_PRESERVE",
        statement: "Do not remove or weaken the authentication assertion.",
      },
    ],
  },
})

Getting Started

DETECT

COMMUNICATE

Project & Configuration

Platform

Configuration

`IcmpMonitor` Options

`IcmpMonitor` Assertions

General Monitor Options

​Configuration

​IcmpMonitor Options

​IcmpMonitor Assertions

​General Monitor Options

Configuration

`IcmpMonitor` Options

`IcmpMonitor` Assertions

General Monitor Options