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
`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

request

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)

degradedPacketLossThreshold

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,
  }
})

maxPacketLossThreshold

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

name

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

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

locations

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

activated

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
})

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