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

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

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