TracerouteMonitor Construct

Learn more about Traceroute Monitors in the Traceroute monitor overview.

Traceroute monitors map the network path to a host hop-by-hop, measuring per-hop latency and packet loss, and detecting whether the destination is reached. Use them to monitor path stability and catch routing issues before they affect your users.

Prerequisites

Before creating Traceroute Monitors, ensure you have:

An initialized Checkly CLI project
A hostname or IP address you want to trace
Basic understanding of network tracing (traceroute / tracert)

For additional setup information, see CLI overview.

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

new TracerouteMonitor('traceroute-api', {
  name: 'API Gateway Network Path',
  description: "Maps the network path to `api.example.com` to detect routing changes.",
  frequency: Frequency.EVERY_5M,
  request: {
    url: 'api.example.com',
  },
})

import { Frequency, TracerouteAssertionBuilder, TracerouteMonitor } from "checkly/constructs"

new TracerouteMonitor('traceroute-db', {
  name: 'Database Routing Monitor',
  description: "Traces path to `db.example.com` with strict latency and hop assertions.",
  activated: true,
  frequency: Frequency.EVERY_10M,
  locations: ['us-east-1', 'eu-central-1'],
  degradedResponseTime: 10000,
  maxResponseTime: 20000,
  request: {
    url: 'db.example.com',
    protocol: 'TCP',
    port: 5432,
    ipFamily: 'IPv4',
    maxHops: 20,
    maxUnknownHops: 10,
    ptrLookup: true,
    timeout: 15,
    assertions: [
      TracerouteAssertionBuilder.hopCount().lessThan(15),
      TracerouteAssertionBuilder.responseTime('avg').lessThan(50),
      TracerouteAssertionBuilder.packetLoss().lessThan(5),
    ],
  },
})

Configuration

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

Traceroute Monitor Settings
General Monitor Settings

Parameter	Type	Required	Default	Description
`request`	`object`	✅	-	Traceroute request configuration object
`degradedResponseTime`	`number`	❌	`10000`	Final-hop avg RTT in milliseconds at which the monitor is marked as degraded
`maxResponseTime`	`number`	❌	`20000`	Final-hop avg RTT in milliseconds 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

`TracerouteMonitor` Options

request

object

required

Traceroute request configuration, including probe protocol, target host, and response validation.Usage:

new TracerouteMonitor('traceroute-monitor', {
  name: 'Network Path Monitor',
  request: {
    url: 'api.example.com',
    protocol: 'TCP',
    port: 443,
    assertions: [
      TracerouteAssertionBuilder.hopCount().lessThan(20),
    ],
  },
})

Parameters:

Parameter	Type	Required	Default	Description
`url`	`string`	✅	-	Target hostname or IP address. Do not include a scheme or port
`protocol`	`string`	❌	`'TCP'`	Probe protocol: `'TCP'` \| `'UDP'` \| `'ICMP'` \| `'SCTP'`
`port`	`number`	❌	`443` (TCP) / `33434` (UDP, SCTP)	Destination port (1–65535). Defaults to `443` for TCP and to `33434` — a high, typically closed port — for UDP/SCTP, so the destination returns ICMP Destination Unreachable to confirm arrival. Ignored (and not sent) when `protocol` is `'ICMP'`
`ipFamily`	`string`	❌	`'IPv4'`	IP family: `'IPv4'` \| `'IPv6'`
`maxHops`	`number`	❌	`30`	Maximum hops to probe (1–64)
`maxUnknownHops`	`number`	❌	`15`	Maximum consecutive unresponsive hops before stopping (1–30)
`ptrLookup`	`boolean`	❌	`true`	Perform reverse-DNS (PTR) lookups on hop IPs
`timeout`	`number`	❌	`10`	Seconds to wait for the trace to complete (1–30)
`assertions`	`TracerouteAssertion[]`	❌	`[]`	Response assertions using `TracerouteAssertionBuilder`

degradedResponseTime

number

default:"10000"

Final-hop average RTT in milliseconds at which the monitor is marked as degraded (warning state). Maximum: 30,000.Usage:

new TracerouteMonitor("traceroute-latency-tiers", {
  name: "API Network Path",
  degradedResponseTime: 5000, // Warn when final-hop avg RTT exceeds 5 seconds
  request: {
    url: 'api.example.com',
  },
})

maxResponseTime

number

default:"20000"

Final-hop average RTT in milliseconds at which the monitor is marked as failed. Maximum: 30,000.Usage:

new TracerouteMonitor("traceroute-latency-tiers", {
  name: "API Network Path",
  maxResponseTime: 15000, // Fail when final-hop avg RTT exceeds 15 seconds
  request: {
    url: 'api.example.com',
  },
})

`TracerouteMonitor` Assertions

Assertions for Traceroute monitors are defined using the TracerouteAssertionBuilder. The following sources are available:

responseTime(property?): Validate RTT at the final responding hop. Pass 'avg', 'min', 'max', or 'stdDev' as the argument to target a specific statistic; when omitted, it defaults to 'avg'. This assertion fails when destinationReached is false
hopCount(): Assert against the total number of hops recorded in the trace
packetLoss(): Assert against the packet loss percentage at the last recorded hop (0–100)

Here are some examples:

Assert that the average final-hop latency is below a threshold (default property is avg):

TracerouteAssertionBuilder.responseTime().lessThan(100)
// Equivalent to:
{ source: 'RESPONSE_TIME', property: 'avg', comparison: 'LESS_THAN', target: '100' }

Assert against a specific RTT property:

TracerouteAssertionBuilder.responseTime('max').lessThan(200)
// Equivalent to:
{ source: 'RESPONSE_TIME', property: 'max', comparison: 'LESS_THAN', target: '200' }

Assert on the number of hops:

TracerouteAssertionBuilder.hopCount().lessThan(15)
// Equivalent to:
{ source: 'HOP_COUNT', comparison: 'LESS_THAN', target: '15' }

Assert on packet loss at the last hop:

TracerouteAssertionBuilder.packetLoss().lessThan(10)
// Equivalent to:
{ source: 'PACKET_LOSS', comparison: 'LESS_THAN', target: '10' }

Learn more in our docs on Assertions.

General Monitor Options

name

string

required

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

new TracerouteMonitor("my-traceroute", {
  name: "API Gateway Network Path",
  /* More options ... */
})

frequency

Frequency

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

new TracerouteMonitor("my-traceroute", {
  name: "API Gateway Network Path",
  frequency: Frequency.EVERY_5M,
  /* More options ... */
})

Available frequencies: 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. Traceroute monitors do not support sub-30-second frequencies (EVERY_10S / EVERY_20S).

locations

string[]

default:"[]"

Array of public location codes where the Traceroute Monitor should run from. Use privateLocations for private locations. Multiple locations help detect regional routing differences.Usage:

new TracerouteMonitor("global-path-monitor", {
  name: "API Path from Multiple Regions",
  locations: ["us-east-1", "eu-central-1", "ap-southeast-1"],
  request: {
    url: 'api.example.com',
  },
})

activated

boolean

default:"true"

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

new TracerouteMonitor("my-traceroute", {
  name: "API Gateway Network Path",
  activated: false, // Disabled monitor
  request: {
    url: 'api.example.com',
  },
})

Getting Started

DETECT

COMMUNICATE

Project & Configuration

Platform

TracerouteMonitor Construct

Configuration

`TracerouteMonitor` Options

`TracerouteMonitor` Assertions

General Monitor Options

​Configuration

​TracerouteMonitor Options

​TracerouteMonitor Assertions

​General Monitor Options

Configuration

`TracerouteMonitor` Options

`TracerouteMonitor` Assertions

General Monitor Options