Skip to main content
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.
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',
  frequency: Frequency.EVERY_1M,
  request: {
    hostname: 'welcome.checklyhq.com',
  },
  degradedPacketLossThreshold: 20, // percentage
  maxPacketLossThreshold: 30, // percentage
})

​
Configuration

ICMP monitors have their own ICMP-specific settings, plus the standard monitor options shared across all check types.
ParameterTypeRequiredDefaultDescription
requestobject✅-ICMP request configuration object
degradedPacketLossThresholdnumber❌10Packet loss percentage at which the monitor is marked as degraded
maxPacketLossThresholdnumber❌20Packet loss percentage at which the monitor is marked as failed

​
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:
ParameterTypeRequiredDefaultDescription
hostnamestring✅-The target host (domain name or IP address)
pingCountnumber❌10Number of ICMP Echo Request packets to send per check run (1-50, default: 10)
assertionsIcmpAssertion[]❌[]Response assertions using the IcmpAssertionBuilder
ipFamilystring❌IPv4IP 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
})